README
¶
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. With SpiceDB, platform teams are armed with the same techniques for stopping this threat that the hyperscale tech companies have been doing for years behind closed doors.
Similar to a relational database, developers define a schema, write data to the database, and query that data in various ways. However, unlike relational databases that use general-purpose SQL, SpiceDB exposes a gRPC API specifcally optimized for authorizing actions in your systems.
Because SpiceDB self-contains data and logic for used for authorization, it 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.
What is Google Zanzibar?
In 2019, Google released the paper "Zanzibar: Google's Consistent, Global Authorization System" 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, 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.
Why SpiceDB?
- World-class engineering: painstakingly built by experts that pioneered the cloud-native ecosystem
- Authentic design: mature and feature-complete implementation of Google's Zanzibar paper
- Proven in production: 5ms p95 when scaled to millions of queries/s, billions of relationships
- Global consistency: consistency configured per-request unlocks correctness while maintaining performance
- Multi-paradigm: caveated relationships combine the best concepts in authorization: ABAC & ReBAC
- Safety in tooling: designs schemas with real-time validation or validate in your CI/CD workflow
- Reverse Indexes: queries for "What can
subjectdo?", "Who can accessresource?"
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
- Red Hat's Insights Platform
- GitPod
- TubiTV China (中文)
- DMM Online Salon (日本語)
Beyond the community, you can also read customer stories for commercial usage of SpiceDB.
Joining the Community
Join our fellow contributors from companies such as GitHub,
Adobe,
Google,
Fastly,
Plaid,
Red Hat, and
Reddit.
SpiceDB is a community project where everyone is invited to participate and feel welcomed. While the project has a technical goal, participation is not restricted to those with code contributions.
CONTRIBUTING.md documents communication, contribution flow, legal requirements, and common tasks when contributing to the project.
You can find issues by priority: Urgent, High, Medium, Low, Maybe. There are also good first issues.
Our documentation is also open source if you'd like to clarify anything you find confusing.
Getting Started
Familiarizing yourself with our learning materials
- Ask questions via GitHub Discussions or our Community Discord
- Read blog posts from the Authzed team describing the project and major announcements
- Watch our YouTube videos about SpiceDB, modeling schemas, leveraging CNCF projects, and more
- Explore the SpiceDB Awesome List that enumerates official and third-party projects built by the community
- Reference community examples for demo environments, integration testing, CI pipelines, and writing schemas
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:
brew install authzed/tap/spicedb authzed/tap/zed
Debian-based Linux users can install SpiceDB packages by adding a new APT source:
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:
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
Running a container
Container images are available for AMD64 and ARM64 architectures on the following registries:
Docker users can run the latest SpiceDB container with the following:
docker run --rm -p 50051:50051 authzed/spicedb serve --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:
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}.
Deploying to Kubernetes
Production Kubernetes users should be relying on a stable release of the SpiceDB Operator. The Operator enforces not only best practices, but orchestrates SpiceDB updates without downtime.
If you're only experimenting, feel free to try out one of our community-maintained examples for testing SpiceDB on Kubernetes:
kubectl apply -f https://raw.githubusercontent.com/authzed/examples/main/kubernetes/example.yaml
Developing your own schema
You can try both SpiceDB and zed entirely in your browser in the hosted Playground thanks to the power of WebAssembly. The Playground app is open source and can also be self-hosted.
If you don't want to start with the examples loadable from the Playground, you can follow a guide for developing a schema or review the the schema language design documentation.
Watch the SpiceDB primer video to get started with schema development:
Trying out the API
For debugging or getting started, we recommend installing zed, the official command-line client. The Playground also has a tab for experimenting with zed all from within your browser.
When it's time to write code, we recommend using one of the existing client libraries whether it's official or community-maintained.
Because every millisecond counts, we recommend using libraries that leverage the gRPC API for production workloads.
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.
Acknowledgements
SpiceDB is a community project fueled by contributions from both organizations and individuals. We appreciate all contributions, large and small, and would like to thank all those involved.
In addition, we'd like to highlight a few notable contributions:
The GitHub Authorization Team for implementing and contributing the MySQL datastore
The Netflix Authorization Team for sponsoring and being a design partner for caveats
The Equinix Metal Team for sponsoring our benchmarking hardware
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
e2e
module
|
|
|
internal
|
|
|
auth
Package auth contains helper methods for authentication.
|
Package auth contains helper methods for authentication. |
|
caveats
Package caveats contains code to evaluate a caveat with a given context.
|
Package caveats contains code to evaluate a caveat with a given context. |
|
datasets
Package datasets defines operations with sets of subjects.
|
Package datasets defines operations with sets of subjects. |
|
datastore
Package datastore contains datastore and revision implementations, proxies (decorators) for datastores, and code common to all datastores.
|
Package datastore contains datastore and revision implementations, proxies (decorators) for datastores, and code common to all datastores. |
|
datastore/common
Code generated by github.com/ecordell/optgen.
|
Code generated by github.com/ecordell/optgen. |
|
developmentmembership
Package developmentmembership defines operations with sets.
|
Package developmentmembership defines operations with sets. |
|
dispatch
Package dispatch contains logic to dispatch requests locally or to other nodes.
|
Package dispatch contains logic to dispatch requests locally or to other nodes. |
|
dispatch/combined
Package combined implements a dispatcher that combines caching, redispatching and optional cluster dispatching.
|
Package combined implements a dispatcher that combines caching, redispatching and optional cluster dispatching. |
|
dispatch/graph
Code generated by github.com/ecordell/optgen.
|
Code generated by github.com/ecordell/optgen. |
|
gateway
Package gateway implements an HTTP server that forwards JSON requests to an upstream SpiceDB gRPC server.
|
Package gateway implements an HTTP server that forwards JSON requests to an upstream SpiceDB gRPC server. |
|
graph
Package graph contains the code to traverse a relationship graph to solve requests like Checks, Expansions and Lookups.
|
Package graph contains the code to traverse a relationship graph to solve requests like Checks, Expansions and Lookups. |
|
lsp
Package lsp implements the Language Server Protocol for SpiceDB schema development.
|
Package lsp implements the Language Server Protocol for SpiceDB schema development. |
|
middleware
Package middleware defines various custom middlewares.
|
Package middleware defines various custom middlewares. |
|
middleware/datastore
Package datastore defines middleware that injects the datastore into the context.
|
Package datastore defines middleware that injects the datastore into the context. |
|
middleware/dispatcher
Package dispatcher defines middleware that injects the dispatcher into the context.
|
Package dispatcher defines middleware that injects the dispatcher into the context. |
|
middleware/handwrittenvalidation
Package handwrittenvalidation defines middleware that runs custom-made validations on incoming requests.
|
Package handwrittenvalidation defines middleware that runs custom-made validations on incoming requests. |
|
middleware/pertoken
Package pertoken defines middleware for testing purposes that injects a new in-memory datastore per incoming bearer token.
|
Package pertoken defines middleware for testing purposes that injects a new in-memory datastore per incoming bearer token. |
|
middleware/readonly
Package readonly defines middleware that injects a read-only proxy of the datastore into the context.
|
Package readonly defines middleware that injects a read-only proxy of the datastore into the context. |
|
middleware/servicespecific
Package servicespecific defines middleware that injects other middlewares.
|
Package servicespecific defines middleware that injects other middlewares. |
|
middleware/streamtimeout
Package streamtimeout defines middleware that cancels the context after a timeout if no new data has been received.
|
Package streamtimeout defines middleware that cancels the context after a timeout if no new data has been received. |
|
middleware/usagemetrics
Package usagemetrics defines middleware that adds usage data (e.g.
|
Package usagemetrics defines middleware that adds usage data (e.g. |
|
namespace
Package namespace provides functions for dealing with and validating types, relations and caveats.
|
Package namespace provides functions for dealing with and validating types, relations and caveats. |
|
relationships
Package relationships contains helper methods to validate relationships that are going to be written.
|
Package relationships contains helper methods to validate relationships that are going to be written. |
|
services
Package services contains all the gRPC controllers.
|
Package services contains all the gRPC controllers. |
|
services/v1/options
Code generated by github.com/ecordell/optgen.
|
Code generated by github.com/ecordell/optgen. |
|
taskrunner
Package taskrunner contains helper code run concurrent code.
|
Package taskrunner contains helper code run concurrent code. |
|
telemetry
Package telemetry implements a client for reporting telemetry data used to prioritize development of SpiceDB.
|
Package telemetry implements a client for reporting telemetry data used to prioritize development of SpiceDB. |
|
testfixtures
Package testfixtures contains code that helps to run tests against datastores.
|
Package testfixtures contains code that helps to run tests against datastores. |
|
testserver
Package testserver defines a test server.
|
Package testserver defines a test server. |
|
pkg
|
|
|
cache
Package cache defines interfaces and implementations of generic in-memory caches.
|
Package cache defines interfaces and implementations of generic in-memory caches. |
|
caveats
Package caveats contains code to compile caveats and to evaluate a caveat with a given context.
|
Package caveats contains code to compile caveats and to evaluate a caveat with a given context. |
|
cmd
Package cmd defines various public and internal commands.
|
Package cmd defines various public and internal commands. |
|
cmd/datastore
Code generated by github.com/ecordell/optgen.
|
Code generated by github.com/ecordell/optgen. |
|
cmd/server
Code generated by github.com/ecordell/optgen.
|
Code generated by github.com/ecordell/optgen. |
|
cmd/testserver
Code generated by github.com/ecordell/optgen.
|
Code generated by github.com/ecordell/optgen. |
|
cmd/util
Code generated by github.com/ecordell/optgen.
|
Code generated by github.com/ecordell/optgen. |
|
composableschemadsl/dslshape
Package dslshape defines the types representing the structure of schema DSL.
|
Package dslshape defines the types representing the structure of schema DSL. |
|
composableschemadsl/parser
parser package defines the parser for the Authzed Schema DSL.
|
parser package defines the parser for the Authzed Schema DSL. |
|
cursor
Package cursor implements encoding and decoding of cursors used in various APIs.
|
Package cursor implements encoding and decoding of cursors used in various APIs. |
|
datastore
Package datastore contains interfaces and code common to all datastores.
|
Package datastore contains interfaces and code common to all datastores. |
|
datastore/options
Code generated by github.com/ecordell/optgen.
|
Code generated by github.com/ecordell/optgen. |
|
development
Package development contains code that runs in the Playground.
|
Package development contains code that runs in the Playground. |
|
diff
Package diff contains code for things that can be diffed (e.g.
|
Package diff contains code for things that can be diffed (e.g. |
|
genutil
Package genutil contains helper functions to deal with generic data (e.g.
|
Package genutil contains helper functions to deal with generic data (e.g. |
|
graph
Package graph contains helper code to traverse a schema.
|
Package graph contains helper code to traverse a schema. |
|
middleware/consistency
Package consistency defines middleware to set, based on the request's consistency level, the right datastore revision to use.
|
Package consistency defines middleware to set, based on the request's consistency level, the right datastore revision to use. |
|
middleware/datastore
Package datastore defines middleware that injects the datastore into the context.
|
Package datastore defines middleware that injects the datastore into the context. |
|
middleware/dispatcher
Package dispatcher defines middleware that injects the dispatcher into the context.
|
Package dispatcher defines middleware that injects the dispatcher into the context. |
|
middleware/logging
Package logging defines middleware to extract fields from requests and set them as fields in the logs.
|
Package logging defines middleware to extract fields from requests and set them as fields in the logs. |
|
middleware/nodeid
Package nodeid defines middleware to update the context with the Id of the SpiceDB node running the request.
|
Package nodeid defines middleware to update the context with the Id of the SpiceDB node running the request. |
|
middleware/requestid
Package requestid defines middleware to set a request or response header with a request ID.
|
Package requestid defines middleware to set a request or response header with a request ID. |
|
middleware/serverversion
Package serverversion defines middleware to return the version of the server.
|
Package serverversion defines middleware to return the version of the server. |
|
middleware/usagemetrics
Package usagemetrics defines middleware that adds usage data (e.g.
|
Package usagemetrics defines middleware that adds usage data (e.g. |
|
migrate
Package migrate provides helper functions to execute datastore migrations.
|
Package migrate provides helper functions to execute datastore migrations. |
|
namespace
Package namespace contains helper functions to create namespaces in a schema.
|
Package namespace contains helper functions to create namespaces in a schema. |
|
releases
Package releases contains helper functions to determine the current and latest version of spiceDB.
|
Package releases contains helper functions to determine the current and latest version of spiceDB. |
|
schema
Package schema contains code that manipulates a schema and knows how to traverse it.
|
Package schema contains code that manipulates a schema and knows how to traverse it. |
|
schemadsl/compiler
Package compiler knows how to build the Go representation of a SpiceDB schema text.
|
Package compiler knows how to build the Go representation of a SpiceDB schema text. |
|
schemadsl/dslshape
Package dslshape defines the types representing the structure of schema DSL.
|
Package dslshape defines the types representing the structure of schema DSL. |
|
schemadsl/parser
parser package defines the parser for the Authzed Schema DSL.
|
parser package defines the parser for the Authzed Schema DSL. |
|
schemautil
Package schemautil contains helper functions to validate and apply changes to a schema.
|
Package schemautil contains helper functions to validate and apply changes to a schema. |
|
testutil
Package testutil implements various utilities to reduce boilerplate in unit tests a la testify.
|
Package testutil implements various utilities to reduce boilerplate in unit tests a la testify. |
|
tuple
Package tuple provides ways to convert to and from proto structs to Go structs that can extend the core functionality.
|
Package tuple provides ways to convert to and from proto structs to Go structs that can extend the core functionality. |
|
validationfile
Package validationfile contains code to manipulate files accepted by the `zed validate` CLI.
|
Package validationfile contains code to manipulate files accepted by the `zed validate` CLI. |
|
x509util
Package x509util contains helper functions to deal with certificates.
|
Package x509util contains helper functions to deal with certificates. |
|
zedtoken
Package zedtoken contains helper functions to handle zedtokens.
|
Package zedtoken contains helper functions to handle zedtokens. |
|
tools
|
|
|
analyzers
Module
|