Built-in Functions

Topaz provides a set of built-in functions that can be used in your policy. These functions make it easier to leverage information found the Topaz directory.

`ds.identity`

ds.identity({
  "key": "<value>"
})

Looks up a user identity by one of the keys (e.g. email address or PID), and returns the id of the user object.

For example: ds.identity({ "key": "euang@acmecorp.com" }) will return dfdadc39-7335-404d-af66-c77cf13a15f8.

`ds.object`

ds.object({
  "id": "<id>"
})

Returns an object instance looked up by its unique <id>.

ds.object({
  "type": "<type>",
  "key": "<value>"
})

Returns an object instance of <type>, looked up by the key supplied as <value>.

For example: ds.object({ "type": "identity", "key": "euang@acmecorp.com" }) will return the identity object associated with Euan.

`ds.relation`

ds.relation({
  "object_id": "<object-id>",
  "object_type": "<object-type>",
  "relation": "<relation-name>",
  "subject_id": "<subject-id>",
  "subject_type": "<subject-type>"
})

Returns the relation instance that connects the subject with the object through the relation identified by <object-type> and <relation-name>.

`ds.check_relation`

ds.check_relation({
  "object": {
    "id": "<object-id>",
    "key": "<object-key>",
    "type": "<object-type>"
  },
  "relation": {
    "name": "<relation-name>",
    "object_type": "<object-type>"
  },
  "subject": {
    "id": "<subject-id>",
    "key": "<subject-key>",
    "type": "<subject-type>"
  }
})

An object can be identified either by its <object-id> or by the combination of its <object-type> and <object-key>. The same is true for a subject.

A relation type is uniquely identified by the object type name and the relation name. A relation instance of that type will relate an object instance to a subject instance.

ds.check_relation returns true if the object instance has a relation of the type specified to the subject instance.

`ds.check_permission`

ds.check_permission({
  "object": {
    "id": "<object-id>",
    "key": "<object-key>",
    "type": "<object-type>"
  },
  "permission": {
    "name": "<permission-name>",
  },
  "subject": {
    "id": "<subject-id>",
    "key": "<subject-key>",
    "type": "<subject-type>"
  }
})

An object can be identified either by its <object-id> or by the combination of its <object-type> and <object-key>. The same is true for a subject.

ds.check_permission returnstrue if the subject has the permission permission-name referenced through one or more relations to the object.

`ds.graph`

ds.graph({
    "id": "<object-id>",
    "object_type": "",
    "object_id": "",
    "subject_type": "",
    "subject_id": "",
    "relation": ""
})

Returns the graph of relations and objects that is anchored in object-id. All other arguments are optional and restrict the graph returned to specific subjects, objects, or relations. The graph will be traversed up until a maximum depth, to avoid infinite recursion through graph cycles.

Built-in Functions

ds.identity​

ds.object​

ds.relation​

ds.check_relation​

ds.check_permission​

ds.graph​