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 key of the user object.

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

ds.object

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": {
"key": "<object-key>",
"type": "<object-type>"
},
"relation": {
"name": "<relation-name>",
"object_type": "<object-type>"
},
"subject": {
"key": "<subject-key>",
"type": "<subject-type>"
},
"with_objects": <boolean>
})

Returns the relation instance that connects the subject with the object through the relation identified by <object-type> and <relation-name>. If with_objects is inclued and set to true, the response includes the full subject and object instances.

ds.check_relation

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

An object is identified 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": {
"key": "<object-key>",
"type": "<object-type>"
},
"permission": {
"name": "<permission-name>",
},
"subject": {
"key": "<subject-key>",
"type": "<subject-type>"
}
})

An object is identified 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({
"anchor": {
"key": "<anchor-key>",
"type": "<anchor-type>"
},
"object": {
"key": "<object-key>",
"type": "<object-type>"
},
"relation": {
"name": "<relation-name>",
"object_type": "<object-type>"
},
"subject": {
"key": "<subject-key>",
"type": "<subject-type>"
}
})

Returns the graph of relations and objects that is anchored in anchor-key. 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.