Skip to main content

Get started with Ory Permissions

Ory Permissions (based on Ory Keto) implements Google Zanzibar. It might differ a bit from other authorization services you know, so let's first clarify a few concepts.

Relations and relation tuples

The data model used by Ory Permissions are so-called relation tuples that encode relations between subjects and objects.

tip

Read the dedicated documents to learn more about subjects and objects.

Examples of relation tuples are:

  • user1 is member of groups:group1
  • member of groups:group1 is reader of files:file1

As you can see, the subject of a relation tuple can either be a specific subject ID, or subjects defined through an indirection (all members of a certain group). The object is referenced by its ID.

Checking permissions

Permissions are just another form of relations. Therefore, a permission check is a request to check whether a subject has a certain relation to an object, possibly through one or more indirections.

As a very simple example, we assume the following tuples exist:

  • user1 is member of groups:group1
  • member of groups:group1 is reader of files:file1

Now, one could ask:

  • Is user1 a reader of files:file1? - Yes, because user1 is a member of groups:group1 and all members of groups:group1 are reader of files:file1.
  • Is user2 a member of groups:group1? - No.

Example

This example setup demonstrates the basics of relation tuple management and usage of the Check API.

Defining namespaces

Relation tuples reside in namespaces. To create relation tuples, you must define their namespace first.

ory patch permission-config <your-project-id> \
--add '/namespaces/-={"id": 0, "name": "resources"}' \
--add '/namespaces/-={"id": 1, "name": "groups"}'

Creating relation tuples

After creating the namespaces, you can use the relation tuple APIs to create a relation tuple.

ORY_PAT="<your ory personal access token from the console>"
ORY_SDK_URL="<your ory project sdk url from the console>"

echo '[
{
"action": "insert",
"relation_tuple": {
"subject_id": "user1",
"relation": "member",
"namespace": "groups",
"object": "group1"
}
}, {
"action": "insert",
"relation_tuple": {
"subject_set": {
"relation": "member",
"namespace": "groups",
"object": "group1"
},
"relation": "owner",
"namespace": "resources",
"object": "file1"
}
}
]' > relationtuple.json

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ORY_PAT" \
-d @relationtuple.json \
"$ORY_SDK_URL/admin/relation-tuples"

Checking permissions

Permission checks are requests that check whether a subject has a relation to an object. This relation can be directly defined, or constructed following indirections (e.g. members of a group).

The Check API allows to perform such checks:

ORY_PAT="<your ory personal access token from the console>"
ORY_SDK_URL="<your ory project sdk url from the console>"

echo '{
"subject_id": "user1",
"relation": "owner",
"namespace": "resources",
"object": "file1"
}' > query.json

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ORY_PAT" \
-d @query.json \
"$ORY_SDK_URL/relation-tuples/check"
# should print:
# {"allowed":true}