Access Control Audit

Aside from providing means to manage access control, another common feature is tools to audit access control.
This is put in place to let application administrators or users themselves understand:

what permissions do users have
how permissions have changed over time

This is intimately related to access-control management but focuses on other types of queries over your application permissions.

Auditing User Permissions: What Permissions Does A User Have Over A Resource?

If you want to determine the computed permission a user has over a resource you can leverage two different APIs in SpiceDB.

ExperimentalReflectSchema (opens in a new tab) lets you query the permissions available for a specific resource. You can even filter by permission name, or a permission name prefix.
BulkCheckPermission (opens in a new tab) lets you perform various permission checks in a single round-trip. This is more efficient than issuing individual checks because SpiceDB will batch many of the subproblems involved.

Auditing Access Grants: How Have Access Grants Changed?

As we described in access-control management, we distinguish access grants from permissions:

user joe being assigned as reader on repository kubernetes is an access grant
user joe having read permission over repository kubernetes is a permission

Access grants describe how a subject can be granted permission to perform an operation over a resource, like for example "a user views repository". A permission is a computation of all the different ways in which a user can be granted (or denied) access, like a direct role grant, indirectly via a team, indirectly as the owner of a top-level organization, temporarily as an auditor...

To understand how access grants in the system have changed over time, you can use SpiceDB Watch (opens in a new tab) API, which lets you stream all relationship changes. Please note that the Watch (opens in a new tab) API is a near real-time streaming API, and thus the application developer is responsible for persisting the audit history according to their needs. By default, SpiceDB holds up to 24 hours of change history, after which it is garbage collected automatically.

Let's assume the traditional GitHub repository authorization model:

definition user {}
 
definition team {
  relation member: user
}
 
definition repository {
  relation role_reader: user | team#member
  relation role_writer: user | team#member
  relation role_adminer: user | team#member
 
  permission read = role_reader + write
  permission write = role_writer + admin
  permission admin = role_adminer
  
}

If you wanted to understand how the access grants to the kubernetes repository have changed over time, you could call the Watch (opens in a new tab) API and filter by resource_type=repository and optional_resource_id=kubernetes.

Auditing Permissions: How Have Permissions Changed?

Auditing permission changes is a very complex problem to solve at scale: that's why we built Authzed Materialize (opens in a new tab).

SpiceDB does not offer an API to stream permission changes, but you could use a combination of APIs to compute a limited audit trail of permission changes. This strategy could also be used to build a materialized index of permissions to Protect a List Endpoint in your application's database.

⚠️

Please note this strategy is very computationally intensive, and it would very likely require scaling out a SpiceDB cluster. It's only likely to work under very narrow use cases that can exploit domain awareness to reduce how many computations need to be run.

Use the Watch (opens in a new tab) API to stream all relationship changes in the system
Use the ExperimentalComputablePermissions (opens in a new tab) API to determine all permissions affected by a relationship change

These two APIs will be used as the foundation to start recomputing permissions, and the more siloed and controlled the use case, the higher the chances this can work at scale.

If you can silo the relationship changes to a specific resource, you could recompute all users that have permission over that resource by running LookupSubjects (opens in a new tab) for each one of the affected permissions determined by ExperimentalComputablePermissions (opens in a new tab). Please note this does not give you the delta of permission changes, that will be the responsibility of the application developer.
However, if you can't exploit the application domain to silo how a permission changes, you'd be forced to recompute all subjects over all available resources, which is a very expensive operation to run to yield a potentially small delta of permission changes.

Auditing SpiceDB API Request and Responses

SpiceDB does not offer an API to determine what API calls it has received. Some alternative options include:

Building a custom middleware for SpiceDB and using the Middleware Framework (opens in a new tab).
Wrapping SpiceDB into another service that acts as the single access point to SpiceDB and thus can audit all access
Retrieving access logs using SpiceDB --grpc-log-requests-enabled and --grpc-log-response-enabled
Using Authzed Audit Logging (opens in a new tab)

Access Control Management Observability Tooling