This guide will explain how to use Ory Keto's expand-API to display who has access to an object, and why. Please refer to the gRPC and REST API reference documentation for all details. In general, the expand-API allows to expand a given subject set into all its effective subjects.
As an example, we want to look at a file sharing application. Files are hierarchically organized in a directory structure. Every user owns files and directories, and can grant any other user access to them on a per-file or per-directory basis. Users can only see and access files they own or were granted access by the owner.
Directories and files are stored in Ory Keto within the
files namespaces respectively. They are identified by a UUID that the
application maps to the actual object metadata. Users are also identified by and
mapped to a UUID.
Displaying who has Access
To assist users with managing permissions for their files, the application has to display exactly who has access to a file and why. In this example, we assume that the application knows the following files and directories:
├─ photos (owner: maureen; shared with laura)
├─ beach.jpg (owner: maureen)
├─ mountains.jpg (owner: laura)
This is represented in Ory Keto by the following relation tuples:
// maureen granted access to /photos to laura
// the following tuples are defined implicitly through subject set rewrites (not supported yet)
// the follwoing tuples are required to allow the subject set rewrites (not supported yet)
maureen now wants to manage
access for the file
/photos/beach.jpg. Therefore, the application uses the expand-API to get a
tree of everyone who has access to that file:
- gRPC Go
- gRPC node.js
- Keto Client CLI
Maximum Tree Depth
max-depth parameter is important to keep the request latency within an
acceptable bound, but also abstract away the most basic subject sets. In many
cases the application does not want to resolve all subject sets, but rather
wants to display that e.g.
Everyone in the company or
Admins have a specific
In this example the application knows the rough structure of the relation tuples
it uses and can therefore determine that
max-depth=3 is sufficient to display
all relevant relations:
- directly granted access (depth 1)
- indirectly granted access through ownership (depth 2)
- indirectly granted access through ownership of the parent (depth 3)
Analyzing the Tree
The tree does not only include the subject IDs (in this case usernames), but also for what reason they were included. This can be useful for users to audits permissions. Also, in many cases the application would not want to list all subject IDs but rather abstract away some subject sets.