Skip to main content

Check whether a user has access to something

This guide will explain how you can use Ory Keto's check-API to determine whether a subject has a specific relation on an object. The result can be used for controlling access to specific resources.

Synchronous authorization flow​

We recommend offloading the whole burden of access control to Ory Keto. Typically, this means that the application forwards every incoming request as a check request to Ory Keto. The following chart demonstrates how such a flow can look like:

Note that the channel of communication between user <-> application, and application <-> Ory Keto can vastly differ. The application could offer a JSON API towards the user, while communicating with Keto through gRPC.

As a first step, the application has to authenticate the user reliably to provide the subject to Keto. This can be achieved by using Ory Identities or any other authentication system.

The request (here decypher of the message 02y_15_4w350m3) is then translated into a request to Ory Keto's check-API. Basically, the application is asking Keto "Is john allowed to decypher the text 02y_15_4w350m3?"

This question is encoded as the following relationship:

messages:02y_15_4w350m3#decypher@john
Important

It's up to the application and its defined relationships how the check requests have to be encoded. In this example we assume that the known cypher messages are stored in Ory Keto and access to the cleartext is encoded by the decypher relation.

Directly defined access​

Ory Keto can know the exact relationship that the application is checking. Intuitively, this means that john was allowed to decypher the message 02y_15_4w350m3 directly (imagine a "Share with john" input in a UI).

Try this yourself by first adding the relationship using the write API (note that the flag --insecure-disable-transport-security is necessary with newer versions of the Keto CLI if you run Keto without TLS):

contrib/docs-code-samples/simple-access-check-guide/00-write-direct-access/main.go

Result

Now, we can use the check-API to verify that john is allowed to decypher the message:

contrib/docs-code-samples/simple-access-check-guide/01-check-direct-access/main.go

Result

Indirectly defined access​

On the other hand, it's possible to indirectly grant john access to the resource. This could be done by adding a group, lets call it hackers. Now we can grant access to the resource to everyone in that group by adding the following relationship to Ory Keto:

messages:02y_15_4w350m3#decypher@(groups:hackers#member)

We also have to make john a member of hackers by adding the relationship:

groups:hackers#member@john

Now, when Keto receives above check request, it will resolve the subject set

groups:hackers#member

and determine that john is a subject in the resulting set. Therefore, it approves the check request.

There is no limit on the number of indirections through subject sets.

Caching Keto responses​

We don't recommend that you cache the responses from Ory Keto. It's designed to respond quickly and still provide some consistency guarantees. For the revocation of access it's important to not use a local cache. Be ensured that Ory Keto heavily utilizes caching wherever possible.

Conclusion​

We learned how to integrate check requests and access control into an application using Ory Keto's check-API.