Userset Rewrites

This guide will explain how to configure your your 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 users or groups of users. Through the Ory Permission Language we 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, you need the following keto.yaml (at contrib/rewrites-example/keto.yaml):

contrib/rewrites-example/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.

Backwards compatibility

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, we create a file with our namespace configuration as follows:

contrib/rewrites-example/namespaces.keto.ts

Editor support

If you are using a text editor with TypeScript support, you can get extra help when using the Ory Permission Language. Just make sure that the file contrib/rewrites-examples/lib.ts is in the same folder as the file you are editing. It contains all definitions to type-check the config.

In the future, we will make the lib file available at an easy-to-import location.

Starting Ory Keto

After you created both configuration files (keto.yaml and namespaces.keto.ts), you can start Ory Keto with:

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

Creating the tuples

Now that Ory Keto is running, we can create the tuples either through the Keto CLI.

We use the following relation tuples to 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.

As usual, it is still possible to create additional fine-grained permission rules for certain objects, as is done for the "private" file.

contrib/rewrites-example/relation-tuples/tuples.json

You can load the file into keto as such:

$ keto relation-tuple create ./contrib/rewrites-example/relation-tuples/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:

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

Patrik can view "keto/src/main.go", because it is in the folder "keto/src", which is in the folder "keto", which has as "viewers" the group "developer", of which Patrik is a member of.

$ keto check User:Patrik view File private
Denied

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

$ keto check User:Henning view File private
Allowed

$ keto check User:Henning edit File private
Allowed

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

Further reading

If you want to dig furhter into the Ory Permission Language, be sure to check out the specification.