Skip to main content


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).


The Topaz Directory stores three types of entities:

  • Object: Objects represent the participants in authorization decisions. Some objects represent subjectsactors who perform actionsand other may represent resourcesthe 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.


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.


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 typeObject typeDescription
MemberGroupA subject is a member of a group
IdentifierIdentityA user is identified by an identity
UserApplicationA user can have applications
ManagerUserA 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.


Authorization policies can access directory contents via a set of built-ins.