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. 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're 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 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 relationships:
// maureen granted access to /photos to laura
// the following tuples are defined implicitly through subject set rewrites (not supported yet)
// the following 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.
You must use the flag
--insecure-disable-transport-security with version v0.9.0 or newer of the Keto CLI if you run Keto without
- 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 doesn't want to resolve all subject sets, but rather wants to display that for
Everyone in the company or
Admins have a specific relation.
In this example the application knows the rough structure of the relationships 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 doesn't 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.