LookupSubjects and SpiceDB v1.12.0

July and August have been busy months for everyone at Authzed!

In addition to the announcement of the SpiceDB Operator and the new WASM based playground, SpiceDB itself received a significant update in the form of version 1.12

Version 1.12 of SpiceDB introduces a number of improvements, the largest of which is a new API called LookupSubjects.

When to use LookupSubjects

The LookupSubjects API provides the ability to find all subjects reachable for a particular resource and permission, acting as a reverse of our previously released LookupResources API.

LookupSubjects is most useful for any user interface or auditing code that needs to determine the full set of users, tokens, or other kinds of subjects which have a particular permission on a resource.

Unlike the ExpandPermissionTree API, LookupSubjects is automatically recursive: it will walk through other kinds of objects, such as groups, to determine the fully resolved set of subjects that have the requested permission. Also unlike the Expand API, LookupSubjects is streaming : it will return results as soon as it can to the caller.

For example, a "who can view this document" panel might use LookupSubjects to determine the full set of users that can view the document, including those who gain access through groups, or a parent organization:

LookupSubjectsRequest {
  Resource: {
    ObjectType: "document"
    ObjectId: "thedocument"
  }

  Permission: "view"

  SubjectObjectType: "user"
}

How LookupSubjects works

In my ACL Filtering in Authzed blog post, I discussed how LookupResources (the inverse to LookupSubjects) functions by walking the permission graph in a "backwards" fashion.

LookupSubjects functions in much the same way, but in the same direction as a Check: starting at the permission requested and the resource type, SpiceDB walks all branches of the permission graph, outward, until it reaches any subjects of the requested type:

We chose to add the LookupSubjects API for two reasons:

1. The ability to find all accessible subjects is incredibly important for auditing and other kinds of UI and was difficult to implement for users: previously, this kind of recursive walk and processing would have to be done by clients themselves via multiple Expand calls, which we recognized as a significant hurdle to adoption.

2. LookupSubjects is one of the two APIs (the other being ReachableResources) necessary to support the WatchResources API, a new API currently being implemented which will stream a set of permission changes whenever a relationship is updated in SpiceDB. This new API will allow users of SpiceDB to store and update the set of accessible resources for a particular kind of subject, and use that set for filtering via RDBMSes, Elastic, and other external querying systems.

Test it now

Want to test LookupSubjects now? Simply create an account on authzed.com or download SpiceDB and then run a zed call:

zed permission lookup-subjects document somedocument view user

Have a question? Check out the Discord, where we and the community are discussing all things SpiceDB