diff options
Diffstat (limited to 'share/man/spicedb/README.md')
| -rw-r--r-- | share/man/spicedb/README.md | 217 |
1 files changed, 139 insertions, 78 deletions
diff --git a/share/man/spicedb/README.md b/share/man/spicedb/README.md index bd6d7798..f5e2e968 100644 --- a/share/man/spicedb/README.md +++ b/share/man/spicedb/README.md @@ -1,91 +1,152 @@ -# Spice DB +# SpiceDB Integration Guide -SpiceDB is a re-implementation of the [Google Zanzibar][1]. +SpiceDB provides relation-based authorization using the Google Zanzibar model. +This service handles complex permission hierarchies through relationship graphs. -## Components +## Architecture -* `zed`: Command line client -* `spicedb`: The Server +``` ++---------------------------------------------------------------------+ +| Client Request | ++---------------------------------------------------------------------+ + | + V ++---------------------------------------------------------------------+ +| Envoy Proxy (:20000) | +| | +| Routes /authzed.api.v1.* directly to SpiceDB | +|---------------------------------------------------------------------+ + | SpiceDB APIs + V + +---------------------+ + | SpiceDB (:50051) | + | | + | +-----------------+ | + | | Relations | | + | | * user:mokhax | | + | | * project:1 | | + | | * maintainer | | + | | * developer | | + | +-----------------+ | + +---------------------+ +``` + +## Authorization Flow + +``` + Client Envoy SpiceDB + | | | + | gRPC PermissionCheck | | + |---------------------->| | + | | Route by gRPC service | + | |----------------------->| + | | | + | | | Query + | | | relations + | | | graph + | | Permission result | + | |<-----------------------| + | | | + | Permission response | | + |<----------------------| | +``` -### zed +## Quick Start + +### 1. Start All Services ```bash -モ zed --help -A command-line client for managing SpiceDB clusters. - -Usage: - zed [command] - -Available Commands: - backup Create, restore, and inspect permissions system backups - completion Generate the autocompletion script for the specified shell - context Manage configurations for connecting to SpiceDB deployments - help Help about any command - import Imports schema and relationships from a file or url - permission Query the permissions in a permissions system - preview Experimental commands that have been made available for preview - relationship Query and mutate the relationships in a permissions system - schema Manage schema for a permissions system - use Alias for `zed context use` - validate Validates the given validation file (.yaml, .zaml) or schema file (.zed) - version Display zed and SpiceDB version information - -Flags: - --certificate-path string path to certificate authority used to verify secure connections - --endpoint string spicedb gRPC API endpoint - -h, --help help for zed - --hostname-override string override the hostname used in the connection to the endpoint - --insecure connect over a plaintext connection - --log-format string format of logs ("auto", "console", "json") (default "auto") - --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") - --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed - --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) - --no-verify-ca do not attempt to verify the server's certificate chain and host name - --permissions-system string permissions system to query - --proxy string specify a SOCKS5 proxy address - --request-id string optional id to send along with SpiceDB requests for tracing - --skip-version-check if true, no version check is performed against the server - --token string token used to authenticate to SpiceDB - -Use "zed [command] --help" for more information about a command. +# Start authzd, envoy, and spicedb +make run ``` +### 2. Setup SpiceDB Schema & Data + +```bash +# Initialize schema and test data +make run-spicedb-setup + +# Test permissions +make run-spicedb-permission-check +``` -### server +### 3. Test SpiceDB Permissions ```bash -モ spicedb --help -A database that stores, computes, and validates application permissions - -Usage: - spicedb [command] - -Examples: - No TLS and in-memory: - spicedb serve --grpc-preshared-key "somerandomkeyhere" - - TLS and a real datastore: - spicedb serve --grpc-preshared-key "realkeyhere" --grpc-tls-cert-path path/to/tls/cert --grpc-tls-key-path path/to/tls/key \ - --http-tls-cert-path path/to/tls/cert --http-tls-key-path path/to/tls/key \ - --datastore-engine postgres --datastore-conn-uri "postgres-connection-string-here" - - -Available Commands: - completion Generate the autocompletion script for the specified shell - datastore datastore operations - help Help about any command - lsp serve language server protocol - serve serve the permissions database - serve-testing test server with an in-memory datastore - version displays the version of SpiceDB - -Flags: - -h, --help help for spicedb - --log-format string format of logs ("auto", "console", "json") (default "auto") - --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") - --skip-release-check if true, skips checking for new SpiceDB releases - -Use "spicedb [command] --help" for more information about a command. +# Check permissions via zed CLI +zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 read user:mokhax ``` -[1]: https://authzed.com/blog/what-is-google-zanzibar +## SpiceDB Configuration + +### Schema Development + +1. Update schema in `etc/authzd/spice.schema` +2. Apply with `zed schema write` +3. Add relationships with `zed relationship create` + +### Schema Example + +```zed +definition user {} +definition project { + relation developer: user + relation maintainer: user + permission read = developer + maintainer + permission write = maintainer +} +``` + +### Creating Relationships + +```bash +# Add user to project as maintainer +zed relationship create project:1 maintainer user:mokhax + +# Add user to project as developer +zed relationship create project:1 developer user:tanuki +``` + +## zed CLI Commands + +### Schema Management + +```bash +# Write schema to SpiceDB +zed --endpoint "localhost:20000" --token "secret" --insecure schema write etc/authzd/spice.schema + +# Read current schema +zed --endpoint "localhost:20000" --token "secret" --insecure schema read +``` + +### Relationship Management + +```bash +# Create relationships +zed --endpoint "localhost:20000" --token "secret" --insecure relationship create project:1 maintainer user:mokhax + +# Delete relationships +zed --endpoint "localhost:20000" --token "secret" --insecure relationship delete project:1 developer user:tanuki +``` + +### Permission Checks + +```bash +# Check specific permissions +zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 write user:mokhax + +# Bulk permission checks +zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 read user:tanuki +``` + +## Make Targets + +- `make run-spicedb-setup` - Initialize schema and test data +- `make run-spicedb-permission-check` - Test permission queries + +## References + +- [SpiceDB Documentation](https://authzed.com/docs) +- [Google Zanzibar Paper](https://authzed.com/blog/what-is-google-zanzibar) +- [Cedar Policy Language](https://docs.cedarpolicy.com/) +- [Envoy External Authorization](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter) |