Relationship-Based Access Control

Relationship-Based Access Control (ReBAC) is part of Descope's Fine-Grained Authorization (FGA) system, which uses the authz service (/v1/mgmt/authz/* endpoints) for authorization operations.

For performance optimization, you can use the FGA Cache to accelerate ReBAC checks.

Understanding ReBAC

Descope supports full Relationship-Based Access Control (ReBAC) to manage access permissions in your application based on relationships between entities. You create a schema to define your authorization model, create relations between entities, and check relations to determine access.

ReBAC with SSO Providers

ReBAC can be integrated with SSO providers to automatically create relations based on group membership from your Identity Provider (IdP). When users authenticate via SSO, groups from the IdP can be mapped to ReBAC relations, automatically granting access based on their group membership.

For example, if a user belongs to the "Engineering" group in your IdP, you can configure ReBAC to automatically create a member relation to an engineering-team resource, granting them access to engineering-specific resources.

For instructions on how to configure ReBAC group mapping with SSO providers, see the SSO FGA Group Mapping documentation.

Why Use Relational Authorization?

ReBAC introduces relationship-based access control to handle scenarios where access depends on the specific relationships between users and resources, not just their roles. You can use ReBAC as a replacement for RBAC when you need more granular control, or as a complement to RBAC when you need both role-based and relationship-based authorization.

When to Use ReBAC

Introduce relational authorization when you need:

• Resource-Specific Access: Access control that varies per resource (e.g., a user owns document A but not document B)
• Dynamic Relationships: Permissions that change based on relationships that evolve over time
• Hierarchical Structures: Access control for nested resources (e.g., folders containing documents)
• Collaborative Access: Multi-user scenarios where access depends on relationships between users and resources
• Contextual Permissions: Permissions that depend on the relationship context (e.g., a user can edit a document they own, but only view documents shared with them)

ReBAC as a Replacement for RBAC

You can use ReBAC to completely replace RBAC when your authorization model is primarily relationship-based. This is ideal when:

• Most access decisions depend on relationships rather than roles
• You need fine-grained, per-resource access control
• Your authorization model is too complex for simple role assignments

ReBAC as a Complement to RBAC

You can use ReBAC alongside RBAC to handle different authorization scenarios:

• RBAC for broad permissions: Use roles for high-level permissions (e.g., "Admin", "Editor", "Viewer")
• ReBAC for resource-specific access: Use relations for fine-grained, per-resource permissions (e.g., "user owns document X", "user is a member of organization Y")

Example: In a document management system:

• RBAC: Defines that users with the "Editor" role can edit documents
• ReBAC: Defines that a specific user owns document "roadmap-2024" and can delete it, while another user is a "viewer" of that same document

Both authorization checks can be performed together to make comprehensive access decisions.

Practical Scenario: E-commerce Platform

Consider an e-commerce platform where you might use both RBAC and ReBAC:

With RBAC alone, access is granted based on roles like Seller, Buyer, or Admin. All sellers have identical access privileges regardless of their specific relationship with buyers or products. This creates limitations:

• One-Size-Fits-All: All sellers have identical access privileges regardless of their specific relationship with the buyer or the product
• Static Permissions: Cannot easily accommodate temporary or conditional permissions

With ReBAC (as complement or replacement), you can add relationship-based access:

• Seller-Customer Relationships: Sellers can give specific customers special access to pre-orders or exclusive products based on their purchase history
• Collaborative Features: For custom-made items, the relationship between a buyer and seller allows direct communication channels
• Dynamic Permissions: Access permissions evolve in real-time (e.g., temporary access to a seller's design tool that expires after order completion)

Using Both Together: You might use RBAC to define that users with the "Seller" role can manage listings, while using ReBAC to define that a specific seller has a "preferred_customer" relationship with certain buyers, granting them exclusive access to certain products.

Key Concepts

Before implementing ReBAC in Descope, it's important to understand the key terms and concepts. For detailed explanations and examples, see the Defining a Schema guide.

Core Components

• Schema: A combination of one or more types that defines your permission model. Learn more about schema structure and DSL syntax.
• Type: Defines a class of objects with similar characteristics (e.g., user, document, folder). See Types in the DSL guide.
• Relation Definitions: Define all possible relations between entities (e.g., owner, editor, viewer). See Relations in the DSL guide.
• Resource: An entity identifier in your system (e.g., note-1, descope.com).
• Target: A unique identifier for a user or entity that can have relations to resources.
• Relation: A tuple connecting a Target to a Resource with a specific relation definition. Learn how to create relations.

Direct and Implied Relations

• Direct Relations: A direct relationship exists when a Relation tuple is explicitly created (e.g., user u1 is the owner of document doc-1).
• Implied Relations: An implied relationship is computed based on the schema. For example, if a user is a member of a group that has owner relation to a document, the user may have implied access through permission definitions.

For complete schema examples and DSL syntax, see the Defining a Schema documentation.

Implementing ReBAC in Descope

The general process of setting up ReBAC in Descope is as follows:

1. Define a schema: Establish the types of entities (e.g., user, document) and the possible relationships (e.g., owner, editor) that exist within your application using the DSL (Domain-Specific Language).
2. Create relations: Build out the actual linkages between specific entities based on your defined schema. These relations represent the real-world relationships (e.g., "user-123 is owner of doc-1") that serve as the foundation for making access decisions.
3. Check relations: Integrate authorization checks into your application to consult the defined relationships and confirm if a user's action is authorized.

Next Steps

Now that you have a high-level overview of ReBAC, let's move on to defining a schema.