Skip to content

chore: move zanzibar faqs to zanzibar page #404

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore: move zanzibar faqs to zanzibar page #404

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 51 additions & 42 deletions pages/spicedb/concepts/zanzibar.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,17 @@ import { Callout } from 'nextra/components'

# Google Zanzibar

Zanzibar is the internal authorization system at Google.
SpiceDB is based on Google Zanzibar, a revolutionary authorization system developed by Google to handle the massive scale and complexity of their services.

A [research paper] publicly documenting the system was published at [2019 USENIX Annual Technical Conference][usenix].
You may recognize the system if you've ever shared access with another user to a Google product like Google Docs or Gmail.

It's designed to provide consistent, secure, and reliable authorization decisions across Google's vast network of applications and users.

A [research paper] publicly documenting the system was published at [2019 USENIX Annual Technical Conference][usenix]. You can check out our [annotated version], which describes the concepts behind its design and implementation.

[research paper]: https://authzed.com/zanzibar
[usenix]: https://www.usenix.org/conference/atc19
[annotated version]: https://authzed.com/zanzibar

## History

Expand Down Expand Up @@ -89,12 +94,22 @@ On June 28th 2021, Zanzibar was presented to the [Papers We Love] New York City

## Differences with SpiceDB

<Callout type="info">
The Annotated Zanzibar paper has multiple sets of annotations!
SpiceDB attempts to remain true to Zanzibar's design principles, but without any assumptions around Google's internal infrastructure and use cases.
As a result, many things in SpiceDB are more flexible to accommodate different kinds of users with different software stacks.
For example, [modeling complex user systems][model-users] is possible in SpiceDB, but in Zanzibar all users must be a uint64 identifier.

Because SpiceDB is not forced on developers as company-wide requirement, the project also values developer experience and making the tooling pleasant to work with.
You can see this in our [Schema Language] and [Playground] which vastly improves the user experience of directly manipulating Protocol Buffers at Google.

You can read it with [annotations highlighting the differences between SpiceDB and Zanzibar][paper-diff], too!
[model-users]: ../modeling/representing-users
[Schema Language]: ../concepts/schema
[Playground]: https://play.authzed.com
[z-diff]: ../concepts/zanzibar#differences-with-spicedb

[paper-diff]: https://authzed.com/zanzibar/#annotations/spicedb
<Callout type="info">
The [Annotated Zanzibar paper] highlights the differences between SpiceDB and Zanzibar!

[Annotated Zanzibar paper]: https://authzed.com/zanzibar/#annotations/spicedb
</Callout>

### Schema Language
Expand Down Expand Up @@ -126,14 +141,21 @@ This disambiguation also allowed SpiceDB to drop the confusing `_this` keyword u
### Reverse Indices

Both Zanzibar and [SpiceDB][spicedb-expand] implement a ["Reverse Index Expand" API][expand].
This API responds with a tree structure that can be awkward for applications to consume, especially when it's ideal to avoid co-mingling permissions logic and application code.

As a result, SpiceDB supports additional APIs to simplify consuming [Reverse Indices] without structure.
In practice, we find that folks prefer a flattened list of results.
However, this API responds with a tree structure that can be awkward for applications to consume, especially when it's ideal to avoid co-mingling permissions logic and application code.

As a result, SpiceDB supports additional APIs: the [LookupResources] and [LookupSubjects] APIs, which are designed to answer the following questions, respectively:

- "What are all of the resources this subject can access?"
- "What are all of the subjects with access to this resource?"

[LookupResources]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupResources
[LookupSubjects]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupSubjects

These APIs make it easier for consumers, because they return a flattened list of results.

[spicedb-expand]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.ExpandPermissionTree
[expand]: https://authzed.com/zanzibar/2DaJ2vLfht:0.Tk3KF4i94:4S
[reverse indices]: ../getting-started/faq#what-is-a-reverse-index

### Datastores

Expand Down Expand Up @@ -162,17 +184,17 @@ SpiceDB is a bit more flexible with the character-set allowed for Object IDs.

Object Types follow the following Regular Expression:

```
^([a-z][a-z0-9_]{1,61}[a-z0-9]\/)*[a-z][a-z0-9_]{1,62}[a-z0-9]$
```
```
^([a-z][a-z0-9_]{1,61}[a-z0-9]\/)*[a-z][a-z0-9_]{1,62}[a-z0-9]$
```

<ObjectTypeDiagram />

Object IDs follow the following Regular Expression:

```
^(([a-zA-Z0-9/_|\\\-=+]{1,})|\\*)$
```
```
^(([a-zA-Z0-9/_|\\\-=+]{1,})|\\*)$
```

<ObjectIDDiagram />

Expand All @@ -187,22 +209,22 @@ This allows SpiceDB to support more complex user systems and perform more powerf

A simple example is a SpiceDB schema modeling both users and API keys:

```zed
definition ApiKey {}
definition User {
relation keys: ApiKey
}
```
```zed
definition ApiKey {}
definition User {
relation keys: ApiKey
}
```

You can now model relations and permissions with either type:

```zed {4}
definition Post {
relation viewer: User
...
permission view = viewer + viewer->keys
}
```
```zed {4}
definition Post {
relation viewer: User
...
permission view = viewer + viewer->keys
}
```

Now developers don't have to implement logic in every app that resolves API Keys because SpiceDB already knows how to resolve them.

Expand All @@ -221,14 +243,6 @@ Now developers don't have to implement logic in every app that resolves API Keys

## FAQ

### What is Google Zanzibar?

Google Zanzibar is a revolutionary authorization system developed by Google to handle the massive scale and complexity of their services.
It's designed to provide consistent, secure, and reliable authorization decisions across Google's vast network of applications and users.
Google published a paper (check out our [annotated copy](https://zanzibar.tech/)) describing the concepts behind its design and implementation.

You may recognize the system if you’ve ever shared access with another user to a Google product like Google Docs or Gmail.
Comment on lines -224 to -230
Copy link
Contributor Author

@miparnisari miparnisari Nov 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this FAQ here made no sense to me 😆


### Is Zanzibar the same as ReBAC?

While Zanzibar is closely associated with ReBAC (Relationship-Based Access Control), it's not exactly the same thing.
Expand All @@ -238,11 +252,6 @@ Zanzibar uses ReBAC as its underlying authorization model.
So, you could say that Zanzibar is a ReBAC system, but it's more than that.
It also encompasses the infrastructure, algorithms, and optimizations that allow it to operate at Google's immense scale.

### How does SpiceDB relate to Google Zanzibar?

SpiceDB is an open source authorization system inspired by Google Zanzibar, designed to provide similar functionality with a focus on being accessible and adaptable to a wider range of use cases.
It shares Zanzibar's core principles,including relationship-based access control (ReBAC), scalability, performance, and strong consistency.

## Recommended Reading

- [Annotated Zanzibar Paper](https://authzed.com/zanzibar)
Expand Down
8 changes: 4 additions & 4 deletions pages/spicedb/getting-started/client-libraries.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,12 @@ Additionally, there are `example` directories in the client libraries that provi
## HTTP Clients

SpiceDB exposes an HTTP API when run with the `--http-enabled` flag.
While Authzed doesn't officially maintain HTTP client libraries, there are [OpenAPI] docs available [here](../api/http-api).
and served by a SpiceDB instance running the HTTP server.
For example:
While Authzed doesn't officially maintain HTTP client libraries, there are [OpenAPI] docs available [here](../api/http-api) and served by a SpiceDB instance running the HTTP server.

Try it out:

```sh
docker run --rm -p 50051:50051 -p 8443:8443 authzed/spicedb serve --http-enabled --grpc-preshared-key <preshared key>
docker run --rm -p 50051:50051 -p 8443:8443 authzed/spicedb serve --http-enabled --grpc-preshared-key foobar
Copy link
Contributor Author

@miparnisari miparnisari Nov 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

all code snippets should work if you copy-paste them


curl localhost:8443/openapi.json
```
Expand Down
35 changes: 1 addition & 34 deletions pages/spicedb/getting-started/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Notably, policy engines cannot implement [Reverse Indices].
However, there are some scenarios where ReBAC systems can benefit from dynamic enforcement.
For these scenarios, SpiceDB supports [Caveats] as a light-weight form of policy that avoids pitfalls present in many other systems.

[Reverse Indices]: #what-is-a-reverse-index
[Reverse Indices]: ../faq/reverse-indices
[caveats]: ../concepts/caveats

## How can I get involved with SpiceDB?
Expand All @@ -56,36 +56,3 @@ If you're looking to contribute code, you can read [CONTRIBUTING.md] in our open

[Discord]: https://authzed.com/discord
[CONTRIBUTING.md]: https://github.com/authzed/spicedb/blob/main/CONTRIBUTING.md

## Zanzibar Questions

### What is a Reverse Index?

>Reverse-index expand answers the question "what does this employee have access to?", which most organizations validate as part of meeting those compliance obligations.
>But, even more critically, organizations use this information to debug access issues and as baseline data to ensure careful data handling.
>
> — Lea Kissner, Zanzibar Coauthor

In SpiceDB, reverse indices often refer to the [LookupResources] and [LookupSubjects] APIs which are designed to answer the following questions, respectively:

- "What are all of the resources this subject can access?"
- "What are all of the subjects with access to this resource?"

[LookupResources]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupResources
[LookupSubjects]: https://buf.build/authzed/api/docs/main:authzed.api.v1#authzed.api.v1.PermissionsService.LookupSubjects

### How does SpiceDB improve on Google's Zanzibar?

At a high-level, SpiceDB attempts to remain true to Zanzibar's design principles, but without any assumptions around Google's internal infrastructure and use cases.
As a result, many things in SpiceDB are more flexible to accomodate different kinds of users with different software stacks.
For example, [modeling complex user systems][model-users] is possible in SpiceDB, but in Zanzibar all users must be a uint64 identifier.

Because SpiceDB is not forced on developers as company-wide requirement, the project also values developer experience and making the tooling pleasant to work with.
You can see this in our [Schema Language] and [Playground] which vastly improves the user experience of directly manipulating Protocol Buffers at Google.

For more specific details, see the documentation on the [Zanzibar][z-diff].

[model-users]: ../modeling/representing-users
[Schema Language]: ../concepts/schema
[Playground]: https://play.authzed.com
[z-diff]: ../concepts/zanzibar#differences-with-spicedb