Defining a Schema
The ReBAC schema is comprised of three main components: namespaces, relation definitions, and relations. Namespaces are top-level entities in your application, like documents, folders, and organizations. Relation definitions defines the relationship between namespaces, like a user being a member of an organization. Relations are the actual relationships between entities, like a specific user being a member of a particular organization.
The general flow of defining a schema involves creating namespaces and relation definitions.
An example schema
Download an example schema here.
Breaking down the schema
Getting into the details of how a schema is constructed, we'll start from a top down approach. The first data type we have is the schema.
Schema
The AuthzSchema
holds the full schema (all namespaces) for a project.
Namespaces
Within the AuthzSchema
, we have the AuthzNamespace
array, which holds all the namespaces of a project.
AuthzRelationDefinition
Within each AuthzNamespace
, we have the AuthzRelationDefinition
array. In this object, have a name
to quickly define a direct relation and the optional
complexDefinition
parameter to define implicit or recursive relations via a tree of AuthzNode
objects.
AuthzNode
Each AuthzNode
object has a nType
to define the type of node it is, including child
, union
, intersect
, or sub
.
- Union (
union
): Combines the permissions of all child nodes. If any of the children grant a permission, that permission is present in the resulting set. - Intersection (
intersect
): Only the permissions common to the child nodes are included. A permission must be granted by every child to be present in the resulting set. - Subtraction (
sub
): Starts with permissions granted by the first child node, then removes any permissions that are also granted by subsequent child nodes. It effectively excludes permissions from the resulting set that are granted by the other nodes.
Optionally, we have:
- The
children
array is an array ofAuthzNode
objects, allowing for a more complex tree structure. - The
expression
parameter is completed with anAuthzNodeExpression
, which defines the relationship between the node, target, and relation definition it is a part of.
Practical Example of Node Types
To delve into a practical example of why we would use these node types, let's look at access management for a document/folder system:
- Node 1 (
union
): Represents editors of a document - Node 2 (
union
): Represents editors of a parent folder which the document resides in.
If we want to determine who has ultimate edit access to the document, we'd look at the union of these two nodes, meaning the editors of the document itself and editors of the parent folder. However, if we would like to exclude certain users from editing specific documents despite having edit permissions on the parent folder or are direct editors, what would we do?
- Node 3 (
sub
): Would be used to subtract specific users or roles that are forbidden from editing this document for some reason, maybe due to a conflict of interest or security protocol.
Using the sub
permissions type we can refine the permissions set to exclude certain users or roles.
The result of the sub
operation will be the final set of users who
are authorized to edit the document after applying the exclusion criteria.
Below is an example of the ReBAC schema for a document that has parent, restricted, and editor relations, leveraging union
and sub
:
AuthzNodeExpression
The AuthzNodeExpression
object is used to define the relationship between the AuthzNode
and the AuthzRelationDefinition
it is a part of.
It takes a type, neType
, to define the type of relation expression it is. Optionally, we have:
relationDefinition
andrelationDefinitionNamespace
to define the relation definition and namespace of the relation definition that the node is a part of.targetRelationDefinition
andtargetRelationDefinitionNamespace
to define the relation definition and namespace of the relation definition that the node is targeting.
When thinking about AuthzNodeExpressions
, it can be good to think about the Resources
, Relation Definitions
, and
Targets
in a table format.
Resource | Relation Definition | Target |
---|---|---|
folder_1 | owner | user_1 |
folder_2 | parent | folder_1 |
This table read right to left, as in:
user_1
is the owner offolder_1
folder_1
is the parent offolder_2
So generally, the Target
is the Relation Definition
of the Resource
.
Next
We'll move on to implementing a schema.