# ADR-008: Cedar Authorization Policy Engine Integration\n\n**Status**: Accepted\n**Date**: 2025-10-08\n**Deciders**: Architecture Team\n**Tags**: security, authorization, cedar, policy-engine\n\n## Context and Problem Statement\n\nThe Provisioning platform requires fine-grained authorization controls to manage access to infrastructure resources across multiple environments\n(development, staging, production). The authorization system must:\n\n1. Support complex authorization rules (MFA, IP restrictions, time windows, approvals)\n2. Be auditable and version-controlled\n3. Allow hot-reload of policies without restart\n4. Integrate with JWT tokens for identity\n5. Scale to thousands of authorization decisions per second\n6. Be maintainable by security team without code changes\n\nTraditional code-based authorization (if/else statements) is difficult to audit, maintain, and scale.\n\n## Decision Drivers\n\n- **Security**: Critical for production infrastructure access\n- **Auditability**: Compliance requirements demand clear authorization policies\n- **Flexibility**: Policies change more frequently than code\n- **Performance**: Low-latency authorization decisions (<10 ms)\n- **Maintainability**: Security team should update policies without developers\n- **Type Safety**: Prevent policy errors before deployment\n\n## Considered Options\n\n### Option 1: Code-Based Authorization (Current State)\n\nImplement authorization logic directly in Rust/Nushell code.\n\n**Pros**:\n\n- Full control and flexibility\n- No external dependencies\n- Simple to understand for small use cases\n\n**Cons**:\n\n- Hard to audit and maintain\n- Requires code deployment for policy changes\n- No type safety for policies\n- Difficult to test all combinations\n- Not declarative\n\n### Option 2: OPA (Open Policy Agent)\n\nUse OPA with Rego policy language.\n\n**Pros**:\n\n- Industry standard\n- Rich ecosystem\n- Rego is powerful\n\n**Cons**:\n\n- Rego is complex to learn\n- Requires separate service deployment\n- Performance overhead (HTTP calls)\n- Policies not type-checked\n\n### Option 3: Cedar Policy Engine (Chosen)\n\nUse AWS Cedar policy language integrated directly into orchestrator.\n\n**Pros**:\n\n- Type-safe policy language\n- Fast (compiled, no network overhead)\n- Schema-based validation\n- Declarative and auditable\n- Hot-reload support\n- Rust library (no external service)\n- Deny-by-default security model\n\n**Cons**:\n\n- Recently introduced (2023)\n- Smaller ecosystem than OPA\n- Learning curve for policy authors\n\n### Option 4: Casbin\n\nUse Casbin authorization library.\n\n**Pros**:\n\n- Multiple policy models (ACL, RBAC, ABAC)\n- Rust bindings available\n\n**Cons**:\n\n- Less declarative than Cedar\n- Weaker type safety\n- More imperative style\n\n## Decision Outcome\n\n**Chosen Option**: Option 3 - Cedar Policy Engine\n\n### Rationale\n\n1. **Type Safety**: Cedar's schema validation prevents policy errors before deployment\n2. **Performance**: Native Rust library, no network overhead, <1 ms authorization decisions\n3. **Auditability**: Declarative policies in version control\n4. **Hot Reload**: Update policies without orchestrator restart\n5. **AWS Standard**: Used in production by AWS for AVP (Amazon Verified Permissions)\n6. **Deny-by-Default**: Secure by design\n\n### Implementation Details\n\n#### Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                  Orchestrator                           │\n├─────────────────────────────────────────────────────────┤\n│                                                         │\n│  HTTP Request                                           │\n│       ↓                                                 │\n│  ┌──────────────────┐                                  │\n│  │ JWT Validation   │ ← Token Validator                │\n│  └────────┬─────────┘                                  │\n│           ↓                                             │\n│  ┌──────────────────┐                                  │\n│  │ Cedar Engine     │ ← Policy Loader                  │\n│  │                  │   (Hot Reload)                   │\n│  │ • Check Policies │                                  │\n│  │ • Evaluate Rules │                                  │\n│  │ • Context Check  │                                  │\n│  └────────┬─────────┘                                  │\n│           ↓                                             │\n│  Allow / Deny                                           │\n│                                                         │\n└─────────────────────────────────────────────────────────┘\n```\n\n#### Policy Organization\n\n```\nprovisioning/config/cedar-policies/\n├── schema.cedar          # Entity and action definitions\n├── production.cedar      # Production environment policies\n├── development.cedar     # Development environment policies\n├── admin.cedar          # Administrative policies\n└── README.md            # Documentation\n```\n\n#### Rust Implementation\n\n```\nprovisioning/platform/orchestrator/src/security/\n├── cedar.rs             # Cedar engine integration (450 lines)\n├── policy_loader.rs     # Policy loading with hot reload (320 lines)\n├── authorization.rs     # Middleware integration (380 lines)\n├── mod.rs              # Module exports\n└── tests.rs            # Comprehensive tests (450 lines)\n```\n\n#### Key Components\n\n1. **CedarEngine**: Core authorization engine\n   - Load policies from strings\n   - Load schema for validation\n   - Authorize requests\n   - Policy statistics\n\n2. **PolicyLoader**: File-based policy management\n   - Load policies from directory\n   - Hot reload on file changes (notify crate)\n   - Validate policy syntax\n   - Schema validation\n\n3. **Authorization Middleware**: Axum integration\n   - Extract JWT claims\n   - Build authorization context (IP, MFA, time)\n   - Check authorization\n   - Return 403 Forbidden on deny\n\n4. **Policy Files**: Declarative authorization rules\n   - Production: MFA, approvals, IP restrictions, business hours\n   - Development: Permissive for developers\n   - Admin: Platform admin, SRE, audit team policies\n\n#### Context Variables\n\n```\nAuthorizationContext {\n    mfa_verified: bool,          // MFA verification status\n    ip_address: String,          // Client IP address\n    time: String,                // ISO 8601 timestamp\n    approval_id: Option<String>, // Approval ID (optional)\n    reason: Option<String>,      // Reason for operation\n    force: bool,                 // Force flag\n    additional: HashMap,         // Additional context\n}\n```\n\n#### Example Policy\n\n```\n// Production deployments require MFA verification\n@id("prod-deploy-mfa")\n@description("All production deployments must have MFA verification")\npermit (\n  principal,\n  action == Provisioning::Action::"deploy",\n  resource in Provisioning::Environment::"production"\n) when {\n  context.mfa_verified == true\n};\n```\n\n### Integration Points\n\n1. **JWT Tokens**: Extract principal and context from validated JWT\n2. **Audit System**: Log all authorization decisions\n3. **Control Center**: UI for policy management and testing\n4. **CLI**: Policy validation and testing commands\n\n### Security Best Practices\n\n1. **Deny by Default**: Cedar defaults to deny all actions\n2. **Schema Validation**: Type-check policies before loading\n3. **Version Control**: All policies in git for auditability\n4. **Principle of Least Privilege**: Grant minimum necessary permissions\n5. **Defense in Depth**: Combine with JWT validation and rate limiting\n6. **Separation of Concerns**: Security team owns policies, developers own code\n\n## Consequences\n\n### Positive\n\n1. ✅ **Auditable**: All policies in version control\n2. ✅ **Type-Safe**: Schema validation prevents errors\n3. ✅ **Fast**: <1 ms authorization decisions\n4. ✅ **Maintainable**: Security team can update policies independently\n5. ✅ **Hot Reload**: No downtime for policy updates\n6. ✅ **Testable**: Comprehensive test suite for policies\n7. ✅ **Declarative**: Clear intent, no hidden logic\n\n### Negative\n\n1. ❌ **Learning Curve**: Team must learn Cedar policy language\n2. ❌ **New Technology**: Cedar is relatively new (2023)\n3. ❌ **Ecosystem**: Smaller community than OPA\n4. ❌ **Tooling**: Limited IDE support compared to Rego\n\n### Neutral\n\n1. 🔶 **Migration**: Existing authorization logic needs migration to Cedar\n2. 🔶 **Policy Complexity**: Complex rules may be harder to express\n3. 🔶 **Debugging**: Policy debugging requires understanding Cedar evaluation\n\n## Compliance\n\n### Security Standards\n\n- **SOC 2**: Auditable access control policies\n- **ISO 27001**: Access control management\n- **GDPR**: Data access authorization and logging\n- **NIST 800-53**: AC-3 Access Enforcement\n\n### Audit Requirements\n\nAll authorization decisions include:\n\n- Principal (user/team)\n- Action performed\n- Resource accessed\n- Context (MFA, IP, time)\n- Decision (allow/deny)\n- Policies evaluated\n\n## Migration Path\n\n### Phase 1: Implementation (Completed)\n\n- ✅ Cedar engine integration\n- ✅ Policy loader with hot reload\n- ✅ Authorization middleware\n- ✅ Production, development, and admin policies\n- ✅ Comprehensive tests\n\n### Phase 2: Rollout (Next)\n\n- 🔲 Enable Cedar authorization in orchestrator\n- 🔲 Migrate existing authorization logic to Cedar policies\n- 🔲 Add authorization checks to all API endpoints\n- 🔲 Integrate with audit logging\n\n### Phase 3: Enhancement (Future)\n\n- 🔲 Control Center policy editor UI\n- 🔲 Policy testing UI\n- 🔲 Policy simulation and dry-run mode\n- 🔲 Policy analytics and insights\n- 🔲 Advanced context variables (location, device type)\n\n## Alternatives Considered\n\n### Alternative 1: Continue with Code-Based Authorization\n\nKeep authorization logic in Rust/Nushell code.\n\n**Rejected Because**:\n\n- Not auditable\n- Requires code changes for policy updates\n- Difficult to test all combinations\n- Not compliant with security standards\n\n### Alternative 2: Hybrid Approach\n\nUse Cedar for high-level policies, code for fine-grained checks.\n\n**Rejected Because**:\n\n- Complexity of two authorization systems\n- Unclear separation of concerns\n- Harder to audit\n\n## References\n\n- **Cedar Documentation**: <https://docs.cedarpolicy.com/>\n- **Cedar GitHub**: <https://github.com/cedar-policy/cedar>\n- **AWS AVP**: <https://aws.amazon.com/verified-permissions/>\n- **Policy Files**: `/provisioning/config/cedar-policies/`\n- **Implementation**: `/provisioning/platform/orchestrator/src/security/`\n\n## Related ADRs\n\n- ADR-003: JWT Token-Based Authentication\n- ADR-004: Audit Logging System\n- ADR-005: KMS Key Management\n\n## Notes\n\nCedar policy language is inspired by decades of authorization research (XACML, AWS IAM) and production experience at AWS. It balances expressiveness\nwith safety.\n\n---\n\n**Approved By**: Architecture Team\n**Implementation Date**: 2025-10-08\n**Review Date**: 2026-01-08 (Quarterly)