Skip to main content

Overview

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

tip

Ory Permissions is available to all users of The Ory Network without additional fees or setup. The API is in a production-ready state. The documentation, integration, and UI are under active development.

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}