Define global permission rules using Ory Permission Language

This guide explains how to configure namespaces and relations using the Ory Permission Language.

The example describes a file store. Individual files are organized in a folder hierarchy, and can be accessed by individual users or groups of users. Using the Ory Permission Language you can specify that if a user has access to a folder, the user also has access to all files in that folder.

Setup and Configuration

First, install Keto. Next, create a keto.yaml file with this basic content:

keto.yaml

In the namespaces key, you see the line config: file://./namespaces.keto.ts. This needs to point to your namespace configuration in the Ory Permission Language.

info

Namespace configurations without the Ory Permission Language are still supported by either specifying the namespaces directly or a "naked" URI, e.g. namespaces: file://.namespaces.yaml.

Next, create a file with the namespace configuration:

namespaces.keto.ts

tip

If you are using a text editor with TypeScript support, you can get extra help when using the Ory Permission Language. Make sure to run npm i @ory/keto-namespaces-types and add a tsconfig.json file with the content:

tsconfig.json

Starting Ory Keto

After you created both configuration files (keto.yaml and namespaces.keto.ts), run this command to start Ory Keto:

$ keto serve --config ./path/to/keto.yaml

Creating the tuples

Now that Ory Keto is running, create relation tuples using the Keto CLI.

The following relation tuples showcase the namespace configuration. In short, it sets up a "developer" group with two members, and a folder hierarchy. Through the rules in the Ory Permission Language, every member of the "developer" group can access the files in the hierarchy.

You can create additional fine-grained permission rules for certain objects, similar to the "private" file.

tuples.json

To load the file into Ory Keto, run this command:

$ keto relation-tuple create tuples.json

NAMESPACE       OBJECT                  RELATION NAME   SUBJECT
Group           developer               members         patrik
Group           developer               members         User:Patrik
Group           developer               members         User:Henning
Folder          keto/                   viewers         Group:developer#members
File            keto/README.md          parents         Folder:keto/
Folder          keto/src/               parents         Folder:keto/
File            keto/src/main.go        parents         Folder:keto/src/
File            private                 owners          User:Henning

Checking for permissions

Now, let's check some permissions! Some queries to try:

Transitive permissions for objects in the hierarchy

Patrik can view keto/src/main.go. This file is in the keto/src folder, which is in keto. The keto directory has the "developer" group as its "viewers". Patrik is a member of the "developer" group.

$ keto check User:Patrik view File keto/src/main.go
Allowed

No transitivity for objects outside the hierarchy

Patrik cannot view the private file, since that file is not part of any folder hierarchy Patrik has access to.

$ keto check User:Patrik view File private
Denied

Fine-grained permissions for any object

Henning can both edit and view the private file, since he is an "owner" of it.

$ keto check User:Henning view File private
Allowed

$ keto check User:Henning edit File private
Allowed

Setup and Configuration​

Starting Ory Keto​

Creating the tuples​

Checking for permissions​

Transitive permissions for objects in the hierarchy​

No transitivity for objects outside the hierarchy​

Fine-grained permissions for any object​

Further reading​