diff options
Diffstat (limited to 'share/man/cedar/README.md')
| -rw-r--r-- | share/man/cedar/README.md | 125 |
1 files changed, 125 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) |