spicedb

SpiceDB sets the standard for authorization that scales.

Scale with
Traffic • Dev Velocity • Functionality • Geography

         

   

 

## What is SpiceDB? SpiceDB is the most mature open source project inspired by Google's internal authorization system: [Zanzibar]. As of 2021, [broken access control became the #1 threat to web security according to OWASP][owasp]. With SpiceDB, platform and product teams can be be protected by answering this question easily: **"can subject X perform action Y on resource Z?"** Similar to a relational database, developers define a **schema**, write data in the form of **relationships**, and then use SpiceDB's clients to issue **permission checks** in their application to determine what actions a user can take on a resource. Other queries are also possible, such as "What can `subject` do?" or "Who can access `resource`?". SpiceDB is often ran as a centralized service shared across product suites and microservice architectures. SpiceDB is focused purely on *authorization* and is designed to be fully agnostic to *authentication* solutions/identity providers. [owasp]: https://owasp.org/Top10/A01_2021-Broken_Access_Control/ ### What is Google Zanzibar? In 2019, Google released the paper "[Zanzibar: Google's Consistent, Global Authorization System][zanzibar]" providing the original inspiration for SpiceDB. The paper presents the design, implementation, and deployment of, Zanzibar, Google's internal system for storing and evaluating access control lists. Originally designed for [Google+ Circles][circles], Zanzibar now sits at the core Google's entire product suite (Calendar, Drive, Maps, Photos, YouTube) and powers the Google Cloud IAM service. While SpiceDB has gone on to innovate well beyond the functionality outlined in the paper, development of SpiceDB aims to always remain faithful to the paper's values and goals. [zanzibar]: https://authzed.com/zanzibar [circles]: https://en.wikipedia.org/wiki/Google+#Circles ### Why SpiceDB? - [**World-class engineering**][about]: painstakingly built by experts that pioneered the cloud-native ecosystem - [**Authentic design**][zanzibar]: mature and feature-complete implementation of Google's Zanzibar paper - [**Proven in production**][1M]: 5ms p95 when scaled to millions of queries/s, billions of relationships - [**Global consistency**][consistency]: consistency configured per-request unlocks correctness while maintaining performance - [**Multi-paradigm**][caveats]: caveated relationships combine the best concepts in authorization: ABAC & ReBAC - [**Safety in tooling**][tooling]: designs schemas with real-time validation or validate in your CI/CD workflow - [**Reverse Indexes**][reverse-indexes]: queries for "What can `subject` do?", "Who can access `resource`?" [about]: https://authzed.com/why-authzed [1M]: https://authzed.com/blog/google-scale-authorization [caveats]: https://netflixtechblog.com/abac-on-spicedb-enabling-netflixs-complex-identity-types-c118f374fa89 [tooling]: https://authzed.com/docs/spicedb/modeling/validation-testing-debugging [reverse-indexes]: https://authzed.com/docs/spicedb/getting-started/faq#what-is-a-reverse-index [consistency]: https://authzed.com/docs/spicedb/concepts/consistency ### Who uses SpiceDB? SpiceDB is a powerful tool in a variety of domains and in organizations of all sizes; we've chosen to highlight a few interesting community members: - [IBM's AI Data & Model Factory Platform](https://youtu.be/4K2a9HcRhXA) - [Red Hat's Insights Platform](https://www.redhat.com/en/technologies/management/insights) - [GitPod](https://github.com/gitpod-io/gitpod/issues/15632) - [TubiTV China (中文)](https://zhuanlan.zhihu.com/p/685603356) - [DMM Online Salon (日本語)](https://inside.dmm.com/articles/salon-datebase-migration-challenges/) Beyond the community, you can also read [customer stories][stories] for commercial usage of SpiceDB. [stories]: https://authzed.com/customers ## Getting Started ### Installing the binary Binary releases are available for Linux, macOS, and Windows on AMD64 and ARM64 architectures. [Homebrew] users for both macOS and Linux can install the latest binary releases of SpiceDB and [zed] using the official tap: ```command brew install authzed/tap/spicedb authzed/tap/zed ``` [Debian-based Linux] users can install SpiceDB packages by adding a new APT source: ```command sudo apt update && sudo apt install -y curl ca-certificates gpg curl https://pkg.authzed.com/apt/gpg.key | sudo apt-key add - sudo echo "deb https://pkg.authzed.com/apt/ * *" > /etc/apt/sources.list.d/fury.list sudo apt update && sudo apt install -y spicedb zed ``` [RPM-based Linux] users can install SpiceDB packages by adding a new YUM repository: ```command sudo cat << EOF >> /etc/yum.repos.d/Authzed-Fury.repo [authzed-fury] name=AuthZed Fury Repository baseurl=https://pkg.authzed.com/yum/ enabled=1 gpgcheck=0 EOF sudo dnf install -y spicedb zed ``` [zed]: https://github.com/authzed/zed [homebrew]: https://docs.authzed.com/spicedb/installing#brew [Debian-based Linux]: https://en.wikipedia.org/wiki/List_of_Linux_distributions#Debian-based [RPM-based Linux]: https://en.wikipedia.org/wiki/List_of_Linux_distributions#RPM-based ### Running a container Container images are available for AMD64 and ARM64 architectures on the following registries: - [authzed/spicedb](https://hub.docker.com/r/authzed/spicedb) - [ghcr.io/authzed/spicedb](https://github.com/authzed/spicedb/pkgs/container/spicedb) - [quay.io/authzed/spicedb](https://quay.io/authzed/spicedb) [Docker] users can run the latest SpiceDB container with the following: ```shell # expose grpc and http. http is used in the examples below. docker run --rm -p 50051:50051 -p 8443:8443 authzed/spicedb serve --http-enabled true --grpc-preshared-key "somerandomkeyhere" ``` SpiceDB containers use [Chainguard Images] to ship the bare minimum userspace which is a huge boon to security, but can complicate debugging. If you want to execute a user session into a running SpiceDB container and install packages, you can use one of our debug images. Appending `-debug` to any tag will provide you an image that has a userspace with debug tooling: ```command docker run --rm -ti --entrypoint sh authzed/spicedb:latest-debug ``` Containers are also available for each git commit to the `main` branch under `${REGISTRY}/authzed/spicedb-git:${COMMIT}`. [Docker]: https://docs.docker.com/get-docker/ [Chainguard Images]: https://github.com/chainguard-images/images ### Write your own schema and relationships Now that you have SpiceDB running, you must define your **schema** and write **relationships** that represent the permissions in your application. There are various way to do this: - Use the [client libraries]. - Use the [hosted Playground] or [run it yourself locally]. The playground contains a set of example schemas and test data for different scenarios. - Use the [zed] CLI. - Use the [gRPC](https://buf.build/authzed/api/docs/main:authzed.api.v1) or the [HTTP](https://authzed.com/docs/spicedb/api/http-api) APIs. For example: ``` … ``` You can follow a [guide for developing a schema] or review the the schema language [design documentation]. Finally, you can watch the [SpiceDB primer video on schema development](https://www.youtube.com/watch?v=AoK0LrkGFDY). [hosted Playground]: https://play.authzed.com [run it yourself locally]: https://github.com/authzed/playground [Playground]: https://github.com/authzed/playground [guide for developing a schema]: https://docs.authzed.com/guides/schema [design documentation]: https://docs.authzed.com/reference/schema-lang ### Query the SpiceDB API You can use the [client libraries] or the [gRPC](https://buf.build/authzed/api/docs/main:authzed.api.v1) and [HTTP](https://authzed.com/docs/spicedb/api/http-api) APIs to query SpiceDB. For example, ``` … ``` You can also issue queries with [zed], the official command-line client. The [Playground] also has a tab for experimenting with `zed` all from within your browser. ### Integrating SpiceDB into Your Application To get an understanding of integrating an application with SpiceDB, you can follow the [Protecting Your First App] guide or review API documentation on the [Buf Registry] or [Postman]. [client libraries]: https://github.com/authzed/awesome-spicedb#clients [Protecting Your First App]: https://docs.authzed.com/guides/first-app [Buf Registry]: https://buf.build/authzed/api/docs [Postman]: https://www.postman.com/authzed/workspace/spicedb/overview ### Deploying to Production The core SpiceDB service has been utilized in production by Authzed since 2021 so you can be confident that it is battle-tested. Moreover, it supports various datastores, including Google Cloud Spanner, CockroachDB, MySQL, and PostgreSQL. Read [this](https://authzed.com/docs/spicedb/concepts/datastores) to learn the best practices for each. You can choose to self-host SpiceDB, or use [AuthZed Cloud], a fully managed service. See a [comparison of the various options](https://authzed.com/docs/authzed/guides/picking-a-product). If you choose to self-host, we recommend deploying SpiceDB using Kubernetes. If you're only experimenting, feel free to try out one of our community-maintained [examples] for [testing SpiceDB on Kubernetes]: ```command kubectl apply -f https://raw.githubusercontent.com/authzed/examples/main/kubernetes/example.yaml ``` For a more detailed guide on the SpiceDB Kubernetes Operator, see [this](https://authzed.com/docs/spicedb/ops/operator). For more best practices on deploying SpiceDB, read our [best practices guide]. [examples]: https://github.com/authzed/examples [testing SpiceDB on Kubernetes]: https://github.com/authzed/examples/tree/main/kubernetes [AuthZed Cloud]: https://authzed.com/cloud/signup?utm_campaign=gh_referral&utm_source=github&utm_medium=spicedb [best practices guide]: https://authzed.com/docs/best-practices #### Telemetry SpiceDB collects anonymous telemetry data to help us understand how the community is using SpiceDB and to help us prioritize features. This telemetry is opt-out and can be disabled via setting `--telemetry-endpoint=""`. For more information on the telemetry we collect, see [telemetry](./TELEMETRY.md). ## More Resources - Ask questions via [GitHub Discussions] or our [Community Discord] - Read [blog posts] from the Authzed team describing the project and major announcements - Follow our [self-guided workshops] on usecases ranging from Updating Web Views, to Securing RAG Pipelines - Watch our [YouTube videos] about SpiceDB, modeling schemas, leveraging CNCF projects, and more - Explore the [SpiceDB Awes