diff options
Diffstat (limited to 'share/man/spicedb')
| -rw-r--r-- | share/man/spicedb/README.md | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/share/man/spicedb/README.md b/share/man/spicedb/README.md new file mode 100644 index 00000000..f5e2e968 --- /dev/null +++ b/share/man/spicedb/README.md @@ -0,0 +1,152 @@ +# SpiceDB Integration Guide + +SpiceDB provides relation-based authorization using the Google Zanzibar model. +This service handles complex permission hierarchies through relationship graphs. + +## Architecture + +``` ++---------------------------------------------------------------------+ +| 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 | | + |<----------------------| | +``` + +## Quick Start + +### 1. Start All Services + +```bash +# 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 +``` + +### 3. Test SpiceDB Permissions + +```bash +# Check permissions via zed CLI +zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 read user:mokhax +``` + +## 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) |