Skip to main content

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.