Skip to main content

Defining a domain model

The authorization model needs to mirror the domain model used by the application. To populate the directory we need to define the domain model which is comprised of objects and relations. To define these objects and relations, we first need to declare object types, and their relations and permissions.

Object types​

Object types define the entities in the system, such as user, department, document, etc. Any declared object type can also be designated as a subject of a relationship, by specifying it as the target of a relation.

For example:

  • document can be defined an object type.
  • user object type is typically used as a subject of a relation.
  • group can function as an object when defining a member relation to a user (subject), or it can function as a subject when defining an owner relation to a document (object).

Relations​

Relations define the relationships between entities, such as member, owner, manager, etc. Relations are defined on object types. In the context of authorization, we can think of relations as roles that can be assigned to subjects. For example, a user can be assigned the owner role for a document. In our policy, we can check whether a relation exists for a subject and an object using the ds.check_relation built-in.

Permissions​

While relations are helpful to model roles, we can associate many permissions to a single role. In the directory, permissions are associated with relations. For example, we can declare that the owner relation confers the can_read, can_write, and can_delete permissions. In our policy, we can check whether a permission exists between a subject and an object using the ds.check_permission built-in.

Defining the domain model​

Create a manifest.yaml to define object types, relations, and permission. For example:

# yaml-language-server: $schema=https://www.topaz.sh/schema/manifest.json
---

model:
  version: 3

types:
  ### display_name: User ###
  user:
    relations:
      manager: user

  ### display_name: Identity ###
  identity:
    relations:
      identifier: user

  ### display_name: Group ###
  group:
    relations:
      member: user | group#member

  ### display_name: Document ###
  document:
    relations:
      owner: user | group#member
      editor: user | group#member
      viewer: user | group#member

    permissions:
      can_read: viewer | editor | owner
      can_write: editor | owner
      can_delete: owner

Loading the manifest​

Load the manifest.yaml file into Topaz by running:

topaz manifest set ./manifest.yaml

Manifest language reference​

A full annotated example of the manifest can be found here.

(Deprecated) v2 model syntax​

# object type (document)
document:
  # object relation (document:owner)
  owner:
    # include permissions of other object relations on the same object type
    union:
    - editor
    - viewer
    # permissions for relation on object type
    permissions:
    - sample.document.delete

  # object relation (document:editor)
  editor:
    # include permissions of other object relations on the same object type
    union:
    - viewer
    # permissions for relation on object type
    permissions:
    - sample.document.create
    - sample.document.update

  # object relation (document:viewer)
  viewer:
    # permissions for relation on object type
    permissions:
    - sample.document.read

Load the manifest.yaml file into Topaz by running:

topaz load manifest.yaml