Google Zanzibar

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

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 (opens in a new tab) publicly documenting the system was published at 2019 USENIX Annual Technical Conference (opens in a new tab). You can check out our annotated version (opens in a new tab), which describes the concepts behind its design and implementation.

History

In the 2010s, a team at Google was formed to secure objects across SaaS products and internal systems. Because a single object could be handled by multiple systems (e.g. the core product and a search system), making the problem one of distributed access control, properly handling end-user access controls required architecting a new system.

In the summer of 2019, researchers at Google published a paper called "Zanzibar: Google's Consistent, Global Authorization system". This paper documented the design and success of the project that went on to handle authorization logic across Google's product portfolio.

Before landing on the name Zanzibar, the project was internally referred to as "Spice". At Google, their mission was to ensure the "ACLs must flow", a reference to "the spice must flow" (opens in a new tab). This theme was chosen because Lea Kissner, one of the co-creators, is a Dune fan (opens in a new tab). In homage, AuthZed maintained a Dune-related naming scheme for their own projects.

Significance

Popularizing ReBAC

Relationship-based Access Control (ReBAC) is a one of the paradigms for the design of authorization systems. The core idea behind ReBAC is that the existence of a chain of relationships between a subject and a resource defines access. This abstraction alone is able to model all other existing authorization paradigms including the very popular RBAC and ABAC designs. The concept was originally described by Carrie Gates in a 2006 paper entitled Access Control Requirements for Web 2.0 Security and Privacy (opens in a new tab) with Facebook cited as an early adopter of this paradigm. However, it wouldn't be until the publication of the Zanzibar paper in 2019 that ReBAC would achieve popularity outside of applications that weren't already leveraging graph abstractions for their data.

As Broken Access Control (opens in a new tab) now tops the OWASP Top 10, ReBAC has become the recommended method for building correct authorization systems (opens in a new tab).

For more information on ReBAC, see the documentation for Relationships.

New Enemy Problem

The New Enemy Problem is a scenario where unauthorized access can occur when changes to permissions and the resources they protect are not updated together consistently. SpiceDB solves this problem with configurable consistency and ZedTokens, its version of Zookies.

The term "Zookies" was first introduced in the Zanzibar paper where solving this problem was a fundamental design goal:

ACL checks must respect the order in which users modify ACLs and object contents to avoid unexpected sharing behaviors. Specifically, our clients care about preventing the "new enemy" problem, which can arise when we fail to respect the ordering between ACL updates or when we apply old ACLs to new content. Consider these two examples:

Example A: Neglecting ACL update order

Alice removes Bob from the ACL of a folder;

Alice then asks Charlie to move new documents to the folder, where document ACLs inherit from folder ACLs;

Bob should not be able to see the new documents, but may do so if the ACL check neglects the ordering between the two ACL changes.

Example B: Misapplying old ACL to new content

Alice removes Bob from the ACL of a document;

Alice then asks Charlie to add new contents to the document;

Bob should not be able to see the new contents, but may do so if the ACL check is evaluated with a stale ACL from before Bob's removal.

— Zanzibar, 2.2 Consistency Model (opens in a new tab)

To dig deeper on the New Enemy Problem and the greater topic of consistency, you can read the following:

Papers We Love Presentation

On June 28th 2021, Zanzibar was presented to the Papers We Love (opens in a new tab) New York City chapter:

Differences with SpiceDB

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 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 (opens in a new tab) which vastly improves the user experience of directly manipulating Protocol Buffers at Google.

The Annotated Zanzibar paper (opens in a new tab) highlights the differences between SpiceDB and Zanzibar!

Schema Language

The Zanzibar paper provides examples of Namespace Configs using the Protocol Buffers text-format. Internally, Google has a plethora of Protocol Buffer tooling to aid developers in generating Namespace Configs.

SpiceDB instead offers a Schema Language that internally compiles into Namespace Configs.

Distinguishing Relations from Permissions

Zanzibar does not disambiguate (opens in a new tab) between relations that define access and those that exist purely in the abstract.

SpiceDB introduces new terms and syntax to differentiate relations into two concepts: Relations and Permissions.

Permissions are best thought of as the "public API" being consumed by applications to check access. Permissions are defined using set semantics referred to in Zanzibar parlance as "computed usersets".

Relations are purely abstract relationships between objects stored in SpiceDB. They can be queried by the API, but we highly recommend only ever calling Permissions from the API because Permissions can be updated to compute access backwards compatibly.

This disambiguation also allowed SpiceDB to drop the confusing _this keyword used in Zanzibar userset rewrites.

Reverse Indices

Both Zanzibar and SpiceDB (opens in a new tab) implement a "Reverse Index Expand" API (opens in a new tab).

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 (opens in a new tab) and LookupSubjects (opens in a new tab) 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?"

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

Datastores

Zanzibar only supports Google's internal Spanner (opens in a new tab) service for tuple-storage.

SpiceDB supports a variety of datastores; including Cloud Spanner (opens in a new tab).

You can learn more about datastores in the Datastores documentation.

Consistency

Zanzibar supports a ContentChangeCheck API (opens in a new tab) and the ability to specify "at least as fresh" as a Zookie.

SpiceDB simplifies this workflow by allowing API requests to specify their consistency behavior in addition to implementing ZedTokens, the analogue of Zanzibar's Zookies.

Identifiers

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]$

Object IDs follow the following Regular Expression:

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

Users

At Google, all users and services are registered with a service called GAIA (Google Accounts and ID Administration). GAIA provides unique identifiers for every entity in the form of a 64-bit integer. Zanzibar is designed with the assumption that any user can be represented using their GAIA ID.

Because users are not as rigidly defined outside of Google, SpiceDB treats users just like any other object. This allows SpiceDB to support more complex user systems and perform more powerful queries.

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

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

You can now model relations and permissions with either type:

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.

Terminology

Zanzibar Term	SpiceDB Term
Tuple	Relationship
Namespace	Object Type
Namespace Config	Object Definition
Userset	Subject Reference
User	Subject Reference
Zookie	ZedToken
Tupleset	Relationship Set
Tupleset Filter	Relationship Filter

FAQ

Is Zanzibar the same as ReBAC?

While Zanzibar is closely associated with ReBAC (Relationship-Based Access Control), it's not exactly the same thing. While Zanzibar is the authorization system designed by Google, ReBAC is an authorization model focused on relationships between objects to determine access.

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.