Directory
The Topaz Directory stores information required to make authorization decisions. It is flexible enough to support different access control strategies including Role-Based Access Control (RBAC), Attribute-Based Access Control (ABAC), and Relationship-Based Access Control (ReBAC).
An authorization decision is an answer to the question "Is subject S allowed to perform action A on resource R?" In other words, authorization decisions determine whether a subject (e.g. user, group, service) has a given permission on a resource (e.g. document, folder, project).
Concepts
The Topaz Directory stores three types of entities:
Object: Objects represent the participants in authorization decisions. Some objects represent subjects—actors who perform actions—and other may represent resources—the items that subjects can attempt to access in various ways.
Permission: an action that subjects may attempt to perform on an object
Relation: A labeled association between a source object (resource) and a target object (subject), which may carry with it a set of permissions.
Using these concepts, an authorization decision can be rephrased as "Does subject S have a relation to resource R, where the relation carries permission P ?"
A relation between a subject and a resource can be defined explicitly, or be implied from group membership. For example, the subject S may be a member of group G, which in turn has a relation that carries permission P with the resource R.
Directory as a Graph
It is convenient to think of the Topaz Directory as a graph in which objects are the nodes and relations the edges. Under this model, the authorization question in the previous section can be rephrased again as "Is there a path from the node S to the node R in which one or more edges have permission P?"
Indeed, the directory API provides methods such as check_relation and check_permission to query and traverse this graph of objects and relations.
Examples
With these building blocks, it's possible to construct expressions like:
- Euan is a member of the Sales-group
- Sales-folder is a parent of the Sales-plan-document
- Sales-group is a viewer of the Sales-folder
- The viewer relation includes the read permission
And answer queries like:
- Does Euan have the read permission on the Sales-plan-document ?
The Topaz directory is able to evaluate this graph query, traversing through these relationship and determining the outcome.
Types
To help define different kinds of objects and specify the relations that may exist between them, the Topaz Directory provides two extensible sets of types:
- Object Types define the kinds of objects (including subjects) that can be created in the directory.
- Relation Types define the kinds of relations that can be created between directory objects.
Built-in Object Types
The Directory is pre-configured with a few types:
- User: a principal (used as a subject)
- Group: used to model a collection of users and/or other groups (can be used as a subject or object)
- Identity: an identifier for a User (e.g. email, PID)
- Application: an object that a User may have a relationship to
- Resource: a generic resource
Built-in Relation Types
The following relation types are also pre-configured:
| Relation type | Object type | Description |
|---|---|---|
| Member | Group | A subject is a member of a group |
| Identifier | Identity | A user is identified by an identity |
| User | Application | A user can have applications |
| Manager | User | A user has a manager |
User-defined types
Object and relation types are extensible. Topaz makes it easy to create your own types which model your resource hierarchy / domain model. For example, you may have Organizations, which may have Folders.
Topaz lets you create these object types in the directory, along with relation types (like Viewer, Editor, Admin, Owner) which model the relationship between these objects and subject types (such as User or Group).
User Context
Policies can reference identity context. A calling application can provide the identity context which is used to load that identity context.
The Authorizer will resolve the user identity in the Directory. It will then load the user context and make it available to the Policy as input.user.
Extensible properties
Each object has a JSON property bag that allows storing additional information for that object.
Built-ins
Authorization policies can access directory contents via a set of built-ins.