Relationship-Based Access Control (ReBAC)

Summary

Relationship-Based Access Control (ReBAC) is an authorization model that determines access based on the relationships between entities. Instead of evaluating role assignments or attribute conditions, ReBAC queries a relationship graph to answer questions like "Is this user an editor of this document?" or "Does this user belong to an organization that owns this project?" In Keymate, ReBAC is implemented through the FGA Engine, which stores relationship tuples, evaluates graph-based queries, and provides the authorization backend for ReBAC policies managed by the Policy Engine.

Why It Exists

Some authorization decisions cannot be expressed through roles or attributes alone. Consider these examples:

• "Allow access to a document if the user is its owner or editor"
• "Allow access to a project if the user belongs to the team assigned to it"
• "Allow access to an Organization's resources if the user is a member of that Organization or any of its parent Organizations"

These decisions depend on the relationship between the requesting user and the target resource. The relationship may traverse multiple levels — a user belongs to a team, the team is assigned to a project, and the project belongs to an Organization. RBAC cannot express this because roles are static assignments that do not encode entity-to-entity connections. ABAC cannot express this efficiently because the relationship graph may be deep and dynamic.

ReBAC solves this by modeling authorization as a graph of typed relationships and evaluating access through graph traversal:

• Relationship-driven decisions — Access depends on how entities are connected, not on static assignments or attribute values
• Hierarchical access — Relationships can be inherited through Organization hierarchies, team memberships, or resource ownership chains
• Fine-grained resource-level control — Each resource can have its own set of relationships, enabling per-object authorization (e.g., document-level sharing)
• Dynamic graph — Applications create, modify, and delete relationships at runtime. Access decisions automatically reflect the current state of the relationship graph

Where It Fits in Keymate

ReBAC operates through the FGA Engine, a dedicated component that manages relationship storage and graph evaluation. When a ReBAC policy is evaluated, the Policy Engine delegates the relationship check to the FGA Engine.

Policy authoring: Administrators create ReBAC policies through the Admin Console or the Policy Engine REST API. Each policy specifies an FGA authorization model, a relationship (relation) to check, and how to map source and target entities from the request context to the FGA graph.

Runtime evaluation: When a permission check reaches the Authorization Decision Provider, the platform resolves the source entity (typically the user) and the target entity (typically the resource) from the request context, then queries the FGA Engine to determine whether the specified relationship exists in the graph.

Boundaries

What ReBAC covers:

• Granting access based on entity-to-entity relationships
• Evaluating hierarchical relationships (e.g., Organization membership, team assignment)
• Supporting multiple FGA authorization models with different relationship types
• Mapping request context fields to source and target entities in the relationship graph

What ReBAC does not cover:

• Static role-based access checks — use RBAC
• Attribute-based conditions (e.g., time, location, HTTP method) — use ABAC
• Composing multiple policy types into a single decision — use PBAC
• Relationship storage and graph management — handled by the FGA Engine component

How It Works

Relationship Model

ReBAC is built on the concept of relationship tuples. A tuple connects two entities through a typed relation:

Element	Description	Example
Source (user)	The entity requesting access	user:jane-doe
Relation	The type of relationship	editor
Target (object)	The entity being accessed	document:quarterly-report

These tuples form a directed graph. Authorization decisions are answered by traversing this graph: "Does a path exist from the source entity to the target entity through the specified relation?"

FGA Authorization Models

The FGA Engine supports multiple authorization models, each defining the entity types and relations available for a specific domain. Examples include:

• document-reader — Defines relations like reader, writer, owner on document entities
• project-owner — Defines relations like owner, member, viewer on project entities
• team-member — Defines relations like member, admin on team entities

When creating a ReBAC policy, the administrator selects an FGA authorization model, which determines the available relations for that policy.

Policy Structure

A ReBAC policy contains these key elements:

Element	Description
Authorization ID	Identifies the FGA authorization model to query
Relation	The relationship type to check (e.g., editor, member, owner)
Source	Maps the requesting entity to the FGA graph. Defined by a schemaName (entity type) and sourceField (field from the request context that provides the entity identifier)
Target	Maps the target entity to the FGA graph. Same structure as source — schemaName and sourceField
Generic Context	Optional additional context fields (name-value pairs) that provide extra parameters for the relationship check

Evaluation Logic

When the Authorization Decision Provider evaluates a ReBAC policy:

1. Entity resolution — The platform extracts the source entity identifier and target entity identifier from the request context using the configured source and target field mappings.
2. FGA query — The platform sends a relationship check to the FGA Engine: "Does source:identifier have the relation relationship with target:identifier in the specified authorization model?"
3. Graph traversal — The FGA Engine traverses the relationship graph, following direct and inherited relationships.
4. Decision — If a valid relationship path exists, the policy produces a positive result. The decision strategy then determines the overall outcome.

Diagram

Example Scenario

Scenario

A document management application needs to allow editing only by users who have an explicit editor relationship with the specific document. The platform uses a ReBAC policy that checks the editor relation in the document FGA model.

Input

• Actor: Authenticated user (user@example.com) who has been granted the editor relationship on document:quarterly-report
• Resource: quarterly-report with scope edit
• Action: Permission evaluation via the Authorization Decision Provider
• Context: clientId: acme-docs, FGA authorization model: document-reader

Expected Outcome

• Decision: GRANT
• Why: The ReBAC policy maps the user to the source entity and the document to the target entity. The FGA Engine finds a tuple (user:user@example.com, editor, document:quarterly-report) in the relationship graph. The relationship exists, so the policy result is positive.

Common Misunderstandings

• "ReBAC replaces RBAC" — ReBAC and RBAC serve different authorization patterns. RBAC is ideal for job-function-based access. ReBAC is ideal for resource-ownership and relationship-based access. They are complementary and can be combined in a PBAC composite policy.

• "Every relationship must be explicitly stored" — The FGA Engine supports relationship inheritance through the authorization model. For example, if owner implies editor, and editor implies reader, storing only the owner relationship automatically grants editor and reader access through graph traversal.

• "ReBAC is only for document sharing" — ReBAC applies to any scenario where access depends on entity relationships: team membership, Organization hierarchy, project assignment, resource ownership, or any custom domain model.

warning

ReBAC policies depend on the FGA Engine having accurate relationship data. Ensure that your application maintains the relationship graph by creating and deleting tuples as relationships change (e.g., when a user is added to a team or removed from a project).

Design Notes / Best Practices

• Design your FGA authorization model before creating ReBAC policies. The model defines the entity types, relations, and inheritance rules. A well-designed model simplifies policy creation and reduces the number of tuples needed.

• Use relationship inheritance to minimize tuple storage. Instead of storing separate reader, writer, and owner tuples for the same user-resource pair, define an inheritance chain (owner → writer → reader) and store only the highest-level relationship.

• Combine ReBAC with RBAC for hybrid access control. Use RBAC for Organization-wide role checks and ReBAC for resource-specific relationship checks. Compose them in a PBAC policy with the appropriate decision strategy.

tip

When debugging ReBAC decisions, verify that the expected relationship tuples exist in the FGA Engine. A DENY result often indicates a missing tuple rather than a misconfigured policy.

Related Use Cases

• Document-level sharing where each user has a specific relationship (viewer, editor, owner) with individual documents
• Project access based on team membership, where teams are assigned to projects
• Organization hierarchy access where parent Organization members inherit access to child Organization resources
• Multi-Tenant resource isolation based on Tenant-to-resource ownership relationships

Related Docs

FGA Engine

Relationship storage, graph queries, and ReBAC evaluation backend.

RBAC

Role-based authorization model for permission management through roles.

PBAC

Compose ReBAC with other models into unified access decisions.

Policy Evaluation Model

How permission requests are evaluated and decisions produced.