diff options
Diffstat (limited to 'share/man')
| -rw-r--r-- | share/man/cedar/README.md | 125 | ||||
| -rw-r--r-- | share/man/spicedb/README.md | 152 |
2 files changed, 277 insertions, 0 deletions
diff --git a/share/man/cedar/README.md b/share/man/cedar/README.md new file mode 100644 index 00000000..ec665d69 --- /dev/null +++ b/share/man/cedar/README.md @@ -0,0 +1,125 @@ +# Cedar Authorization Guide + +Cedar provides policy-based authorization using Amazon's Cedar policy +language. This service handles request authorization through Envoy's +`ext_authz` filter. + +## Architecture + +``` ++---------------------------------------------------------------------+ +| Client Request | ++---------------------------------------------------------------------+ + │ + V ++---------------------------------------------------------------------+ +│ Envoy Proxy (:20000) | +│ | +│ * JWT Filter extracts x-jwt-claim-sub header | +│ * ext_authz sends CheckRequest to authzd | ++---------------------------------------------------------------------+ + | ext_authz + V + +---------------------+ + | authzd (:50052) | + | | + | +-----------------+ | + | | Cedar Policies | | + | | * Static Assets | | + | | * JWT Claims | | + | | * Path Rules | | + | +-----------------+ | + +---------------------+ +``` + +## Authorization Flow + +``` + Client Envoy authzd + | | | + | HTTP Request + JWT | | + |---------------------->| | + | | Extract JWT claims | + | | Add x-jwt-claim-sub | + | | | + | | ext_authz CheckRequest | + | |----------------------->| + | | | + | | | Evaluate + | | | Cedar + | | | policies + | | Allow/Deny | + | |<-----------------------| + | | | + | Forward request | | + | or 403 Forbidden | | + |<----------------------| | +``` + +## Cedar Policies + +### Policy Structure + +Policies are stored in `etc/authzd/*.cedar` files using Cedar's policy language: + +```cedar +permit ( + principal == User::"1", + action == Action::"GET", + resource == Resource::"/sparkle/" +) +when +{ + context has host && + context.host == "sparkle.staging.runway.gitlab.net" && + principal has username +}; +``` + +## JWT Integration + +### JWT Header Extraction + +Envoy's JWT filter extracts claims and adds them as headers: + +- `x-jwt-claim-sub` - User ID (subject) + +## Policy Development + +### Adding New Policies + +1. Create or edit `.cedar` files in `etc/authzd/` +2. Use Cedar policy syntax for rules +3. Test with `make test` +4. Validate with `make lint` + +### Policy Validation + +```bash +# Check policy syntax +cedar check-parse --policies etc/authzd/policy1.cedar + +# Format policies +cedar format --policies etc/authzd/policy1.cedar --check +``` + +### Testing Policies + +```bash +# Run Cedar authorization tests +cargo test authorization::cedar_authorizer_test + +# Test specific scenarios +cargo test test_sparkle_homepage +``` + +## Make Targets + +- `make test` - Run all tests including Cedar policy tests +- `make lint` - Validate Cedar policy syntax and formatting + +## References + +- [Cedar Policy Language](https://docs.cedarpolicy.com/) +- [Cedar Language Guide](https://docs.cedarpolicy.com/policies/syntax.html) +- [Envoy JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter) 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) |