From d486c87a0eec5cf5432f6ac968dde76e0ec2500f Mon Sep 17 00:00:00 2001 From: Maria Ines Parnisari Date: Fri, 31 Oct 2025 16:55:56 -0700 Subject: [PATCH] chore: organize zanzibar faqs --- pages/spicedb/concepts/zanzibar.mdx | 93 ++++++++++--------- .../getting-started/client-libraries.mdx | 8 +- pages/spicedb/getting-started/faq.mdx | 35 +------ 3 files changed, 56 insertions(+), 80 deletions(-) diff --git a/pages/spicedb/concepts/zanzibar.mdx b/pages/spicedb/concepts/zanzibar.mdx index 873842e..cbe8a4f 100644 --- a/pages/spicedb/concepts/zanzibar.mdx +++ b/pages/spicedb/concepts/zanzibar.mdx @@ -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 @@ -89,12 +94,22 @@ On June 28th 2021, Zanzibar was presented to the [Papers We Love] New York City ## Differences with SpiceDB - - 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 + + The [Annotated Zanzibar paper] highlights the differences between SpiceDB and Zanzibar! + + [Annotated Zanzibar paper]: https://authzed.com/zanzibar/#annotations/spicedb ### Schema Language @@ -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 @@ -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]$ + ``` Object IDs follow the following Regular Expression: -``` -^(([a-zA-Z0-9/_|\\\-=+]{1,})|\\*)$ -``` + ``` + ^(([a-zA-Z0-9/_|\\\-=+]{1,})|\\*)$ + ``` @@ -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. @@ -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. - ### Is Zanzibar the same as ReBAC? While Zanzibar is closely associated with ReBAC (Relationship-Based Access Control), it's not exactly the same thing. @@ -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) diff --git a/pages/spicedb/getting-started/client-libraries.mdx b/pages/spicedb/getting-started/client-libraries.mdx index f233e28..eb804d6 100644 --- a/pages/spicedb/getting-started/client-libraries.mdx +++ b/pages/spicedb/getting-started/client-libraries.mdx @@ -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 +docker run --rm -p 50051:50051 -p 8443:8443 authzed/spicedb serve --http-enabled --grpc-preshared-key foobar curl localhost:8443/openapi.json ``` diff --git a/pages/spicedb/getting-started/faq.mdx b/pages/spicedb/getting-started/faq.mdx index 88307fb..90b5462 100644 --- a/pages/spicedb/getting-started/faq.mdx +++ b/pages/spicedb/getting-started/faq.mdx @@ -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? @@ -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