Skip to main content

What is ReBAC?

Product overview: ReBAC

Learn what relationship-based access control (ReBAC) is and the terms Permit.io uses to model it: resource roles, role assignments, role derivations, and relationship tuples. This page is for developers deciding whether their application needs ReBAC before they build a ReBAC policy.

ReBAC is a policy model that grants access based on how users and resources are connected, such as a user who owns a folder, or a file that sits in that folder.

Policy as a graph​

ReBAC extends role-based access control (RBAC). RBAC grants a role on a whole resource type. ReBAC also considers the relationships between users and specific resource instances, so you can write policies for hierarchical structures such as folders and files.

You can draw a ReBAC model as a graph. Each node is a user or a resource instance, and each edge is a relationship. Graphs map hierarchies and nested relationships, such as nested folders, organizations, and teams.

Example

A shared file system such as Google Drive is a common ReBAC use case. Graph of a folder named Bob's Files that contains the folders Bob's Docs and Bob's Pics, each containing files The graph shows a folder named Bob's Files. The folder contains two folders, Bob's Docs and Bob's Pics, and each of those folders contains files.

The following sections define the terms you use to control access to these files.

Resource roles​

A resource role is a role that applies to a specific resource type. The role and its permissions apply only to instances of that resource.

Permit writes resource roles, instances, and roles on instances with the keys of the objects, in these three forms:

FormMeansExample
resource:instanceOne instance of a resource typefolder:bobs_files
resource#roleA role on a resource typefolder#owner
resource:instance#roleA role on one instancefolder:bobs_files#owner

The dashboard shows the display names you entered, such as Folder#Owner for the role owner on the resource folder. This page uses the keys.

Resource roles combined with role derivations let a role on one instance grant roles on related instances in a hierarchy.

Example

In the file system example, a user assigned the owner role on the folder bobs_files holds folder:bobs_files#owner.

Graph of the user Bob connected to the Bob's Files folder by an Owner relationship

Role assignment​

A role assignment grants a user a role, and with it all the permissions of that role. You manage the permissions of a role once, instead of granting each permission to each user.

A ReBAC role assignment differs from an RBAC role assignment in scope. An RBAC role assignment applies across the tenant, to every instance of the resource types the role has permissions on. A ReBAC role assignment applies to one resource instance, such as folder:bobs_files#owner.

Role derivation​

A role derivation grants a user a role on a resource instance without a direct role assignment on that instance. The user gets the role from a role they hold on a related instance.

A role derivation needs two parts:

  1. A derivation rule between two resource roles.

    Example

    A rule that derives file#editor from folder#admin: a user with the admin role on a folder also gets the editor role on every file related to that folder.

  2. A relationship tuple between two resource instances. When the tuple exists, a user with a role on one instance gets the derived role on the related instance.

    Example

    A user who holds folder:documents#admin gets file:finance_doc#editor once a relationship tuple connects folder:documents and file:finance_doc.

Role derivations use the relationship data you sync to Permit, so you don't write a condition for every object.

Relationship tuples​

A relationship tuple records a relationship between two specific resource instances. A tuple has three parts: a subject instance, a relation, and an object instance. The policy decision point (PDP) evaluates relationship tuples to decide whether a derived role applies.

Example

In a healthcare application, a relationship tuple could look like this:

subject:  department:cardiology
relation: parent
object:   medical_record:john_smith

The tuple states that the cardiology instance of the department resource is the parent of the john_smith instance of the medical_record resource. With a role derivation from department#doctor to medical_record#viewer, every user who holds department:cardiology#doctor can view medical_record:john_smith, without an assignment on the record itself. When a doctor requests the record, the PDP reads the tuple and the derivation to decide.

Common relationship types​

Parent-child hierarchies​

A parent-child hierarchy nests resources under other resources, as files sit in folders in a file system. A hierarchy can have any number of levels.

Example

A parent-child relationship lets you derive roles between a folder and its files: Graph of Bob as Owner of the Bob's Files folder, with Parent relationships from that folder to its subfolders and from each subfolder to its files The ReBAC policy for this graph is:

A user with the folder#owner role on a folder instance gets the file#owner role on a file instance when the relationship tuple folder:<folder_key> parent file:<file_key> exists.

What a parent-child derivation covers

A user who holds folder:<folder_key>#owner holds file#owner on every file whose parent is that folder, including the files you add to the folder later. You don't create a relationship between the user and each file.

Organizations​

An organization relationship grants permissions based on group membership. You add users to a group, and derive their permissions from the group instead of granting permissions to each user.

Example

Graph of the users Bob, Sam, and Linda as Members of the HR Group, which has an Editor relationship with the Legal Docs and Employee Data resources Bob, Sam, and Linda are members of the HR Group. To give all three edit access to the legal documents, you don't assign each of them an editor role on each document. You make them members of the HR Group, and use this policy:

A user with the group#member role on the group:hr instance gets the document#editor role on a document instance when the relationship tuple group:hr parent document:<document_key> exists.

What an organization relationship covers

Every member of group:hr holds document#editor on every document whose parent is group:hr. The policy stays the same when you add members to the group, or documents under the group.

Implementing ReBAC​

In Permit, you define ReBAC policies on the Policy screen and sync relationship data with the Permit API or SDKs. For a working example, see the healthcare demo application in the Galactic Health Corporation GitHub repository.

Where to start

Draw your resources as nodes and the relationships between them as edges on a graph. The graph shows which relations, resource roles, and role derivations your policy needs.

To define the policy in Permit, follow Building ReBAC policies.

Fun fact

Google's Zanzibar system, which models permissions as a graph of relationships, was described in the paper "Zanzibar: Google's Consistent, Global Authorization System" at the 2019 USENIX Annual Technical Conference. Read the paper on USENIX's site.

Next steps​

Contents

Edit this page

Need help?