From fd64170ad2ef59398faa6112bee229f98b0d5968 Mon Sep 17 00:00:00 2001 From: Gabriel Manor Date: Fri, 28 Jun 2024 00:40:03 -0700 Subject: [PATCH 1/2] ReBAC role assignment and derivation fix --- docs/how-to/build-policies/rebac/overview.mdx | 29 ++++++++++++------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/how-to/build-policies/rebac/overview.mdx b/docs/how-to/build-policies/rebac/overview.mdx index 0ab68b98..4acb7b45 100644 --- a/docs/how-to/build-policies/rebac/overview.mdx +++ b/docs/how-to/build-policies/rebac/overview.mdx @@ -48,19 +48,26 @@ Role Assignment refers to designating specific roles to individual users or enti Roles represent a collection of permissions. By assigning a user a particular role, you're essentially giving them access to all the permissions bundled within that role. This mechanism simplifies access management, especially in large systems or organizations, as administrators only need to manage roles rather than each specific permission for every user. -:::tipExample -New employees in the marketing department might be assigned the `Marketing` role, which provides access to relevant databases, software, and internal websites without having to configure each access permission individually. -::: +ReBAC role assignment is different than RBAC role assignment, becuase it assigned to a specific instance, and not to the whole resource type scope. ### Role Derivation - -ReBAC allows us to derive authorization policies based on existing application-level relationships. Put in the simplest way, it allows us to create a policy like this: - -``` -A `user` assigned the role of `Owner` on a folder will get the `Owner` role on every `file` within that `folder`. -``` - -Creating policies based on relationships rather than roles or attributes saves us from having to create authorization policies on a per-instance basis. +The ReBAC role derivation functionality allows implicit granting of permissions to a user without an explicit role assignment to an instance. + +There are two steps to achieve such an implicit grant of permissions: +1. Configure a derivation between two roles in our system. + + :::tipExample + A user with a role `Admin` on a `Folder` resource will also get an implicit assignment of an `Editor` to all the `File` resource instances that related to that folder. + ::: +2. When a relationship tuple is created between resources, a user with an explicit grant to one resource will implicitly grant permissions to the resources that have a relationship with. + + :::tipExample + A user with an assignment of an `Admin` role to a `Documents` folder will implicitly get the role `Editor` on file `finance.doc` if the `Documents` instance of a resource `Folder` have a relationship with the instance `finance.doc` of type `File` + ::: + +With role derivations, implicit permission is granted to users based on the relationship data in the system without an explicit condition for every object on the system. + +Role derivation is the building block in ReBAC that leverage the relationships between instances to relationships of permissions. ### Relationship Tuples From ad1fb72ba177aeec8a6c64077712acb14554f7af Mon Sep 17 00:00:00 2001 From: Daniel Bass <94785484+danielbass37@users.noreply.github.com> Date: Fri, 28 Jun 2024 11:55:07 +0200 Subject: [PATCH 2/2] Grammar --- docs/how-to/build-policies/rebac/overview.mdx | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/how-to/build-policies/rebac/overview.mdx b/docs/how-to/build-policies/rebac/overview.mdx index 4acb7b45..68868b8c 100644 --- a/docs/how-to/build-policies/rebac/overview.mdx +++ b/docs/how-to/build-policies/rebac/overview.mdx @@ -26,7 +26,7 @@ To understand how ReBAC helps us manage access to these files, we need to unders ### Resource Roles -To create ReBAC policies, we need to create roles **specific to a given resource**. This means that the role, and the permissions it carries, are only relevant in the context of that specific resource. +To create ReBAC policies, we need to create roles **specific to a given resource**. This means that the role and the permissions it carries are only relevant in the context of that specific resource. A resource role is formatted as `Resource#Role`. The combination of **Resource Roles** and **Role Derivations** allows us to derive much more complex and granular roles that are perfectly tailored to handle hierarchies. @@ -38,40 +38,40 @@ In the context of our previous example, A `user` who is assigned the role of an `Owner` on a `folder` ``` -Will look like this: `Folder#Owner`. +It will look like this: `Folder#Owner`. ![Resource Roles](/ui-videos/rebac/2.png) ::: ### Role Assignment -Role Assignment refers to designating specific roles to individual users or entities, effectively granting them the permissions associated with those roles. +Role Assignment refers to designating specific roles for individual users or entities, effectively granting them the permissions associated with those roles. Roles represent a collection of permissions. By assigning a user a particular role, you're essentially giving them access to all the permissions bundled within that role. This mechanism simplifies access management, especially in large systems or organizations, as administrators only need to manage roles rather than each specific permission for every user. -ReBAC role assignment is different than RBAC role assignment, becuase it assigned to a specific instance, and not to the whole resource type scope. +ReBAC role assignment is different from RBAC role assignment because it is assigned to a specific instance and not to the whole resource type scope. ### Role Derivation -The ReBAC role derivation functionality allows implicit granting of permissions to a user without an explicit role assignment to an instance. +The ReBAC role derivation functionality allows a user to be granted implicit permissions without an explicit role assignment to an instance. There are two steps to achieve such an implicit grant of permissions: 1. Configure a derivation between two roles in our system. :::tipExample - A user with a role `Admin` on a `Folder` resource will also get an implicit assignment of an `Editor` to all the `File` resource instances that related to that folder. + A user with a role `Admin` on a `Folder` resource will also get an implicit assignment of an `Editor` to all the `File` resource instances related to that folder. ::: -2. When a relationship tuple is created between resources, a user with an explicit grant to one resource will implicitly grant permissions to the resources that have a relationship with. +2. When a relationship tuple is created between resources, a user with an explicit grant to one resource will implicitly gain permissions to any resources it has a relationship with. :::tipExample - A user with an assignment of an `Admin` role to a `Documents` folder will implicitly get the role `Editor` on file `finance.doc` if the `Documents` instance of a resource `Folder` have a relationship with the instance `finance.doc` of type `File` + A user with an assignment of an `Admin` role to a `Documents` folder will implicitly get the role `Editor` on file `finance.doc` if the `Documents` instance of a resource `Folder` has a relationship with the instance `finance.doc` of type `File` ::: With role derivations, implicit permission is granted to users based on the relationship data in the system without an explicit condition for every object on the system. -Role derivation is the building block in ReBAC that leverage the relationships between instances to relationships of permissions. +Role derivation is the building block of ReBAC that leverages the relationships between instances to define relationship-based permissions. ### Relationship Tuples -Relationship Tuples are structured sets that detail the relationships between resources and potentially users in the system. +Relationship Tuples are structured sets that detail the relationships between resources and, potentially, users in the system. They represent the relationships between two specific instances of resources, providing a clear way to express and evaluate relationships in access control decisions. :::tipExample @@ -108,7 +108,7 @@ In simpler words, if a file resides inside a folder (That’s the Parent-Child r ### Organizations -An organizational relationship allows us to create policies based on groups of users. Putting several users in one group allows us to derive policies based on their group membership, instead of per individual user. +An organizational relationship allows us to create policies based on groups of users. Putting several users in one group allows us to derive policies based on their group membership instead of per individual user. :::tipExample Take a look at this example: @@ -123,8 +123,8 @@ A `user` assigned the role `HR_Group#Member` will also be assigned the `Legal_Do ::: :::infoThe benefit of organizational relationships -Using organizational relationships allows us to give every user editing permissions for every file, without the need to set an explicit direct relationship between each user and each file. -If we decide to add members or resources to the group, the policy's logic remains valid, and we wouldn’t have to update it for every change we make. +Using organizational relationships allows us to give every user editing permissions for every file without setting an explicit direct relationship between each user and each file. +If we decide to add members or resources to the group, the policy's logic remains valid, and we don’t have to update it for every change. ::: ## Implementing ReBAC @@ -134,7 +134,7 @@ You can see a working example of this healthcare demo application modeled using :::tipWhere to start? The first step to understanding how ReBAC should be implemented into your application is to visually map out the resources you want to manage access to via relationships. -This can be done by putting all of your resources (As nodes) and the relationships between them (As edges) on a graph. This should allow you to better visualize the policies you would need to create. +This can be done by putting all of your resources (as nodes) and the relationships between them (as edges) on a graph. This should allow you to visualize the policies you need to create better. ::: -To learn how to map out and impliment ReBAC using Permit, head on to this section on **[Building ReBAC policies](/how-to/build-policies/rebac/building-rebac-policies)** +To learn how to map out and implement ReBAC using Permit, head on to this section on **[Building ReBAC policies](/how-to/build-policies/rebac/building-rebac-policies)**