provisioning/config/cedar-policies/README.md

Cedar Authorization Policies

This directory contains Cedar policy files for the Provisioning platform authorization system.

Overview

Cedar is a language for defining permissions as policies, which describe who should have access to what. It is purpose-built to be ergonomic, fast, and safe.

Key Features

• Declarative Authorization: Define permissions as policies, not code
• Type-Safe: Schema-based validation prevents errors
• Fast: High-performance authorization engine
• Auditable: All policies are version-controlled
• Hot-Reload: Policies reload automatically on changes

Policy Files

schema.cedar

Defines entity types, actions, and their relationships:

• Entities: User, Team, Environment, Workspace, Server, Taskserv, Cluster, Workflow
• Actions: create, delete, update, read, list, deploy, rollback, ssh, execute, monitor, admin
• Context: MFA verification, IP address, time windows, approval IDs

production.cedar

Production environment policies (strictest security):

• ✅ MFA required for all deployments
• ✅ Approval required for deployments and deletions
• ✅ Business hours restriction (08:00-18:00 UTC)
• ✅ IP address restrictions (corporate network only)
• ✅ SSH access limited to platform-admin and SRE teams
• ❌ Force deletion forbidden without emergency approval

development.cedar

Development environment policies (relaxed):

• ✅ Developers have full access
• ✅ No MFA required
• ✅ No approval required
• ✅ Force deletion allowed
• ✅ Self-service workspace creation
• ✅ Cluster size limited to 5 nodes

admin.cedar

Administrative policies:

• ✅ Platform admins have unrestricted access
• ✅ Emergency access with special approvals
• ✅ Audit team has read-only access
• ✅ SRE team has elevated permissions
• ✅ Security team can perform lockdowns

Policy Examples

Basic Permission

// Allow developers to read resources
permit(
  principal in Team::"developers",
  action == Action::"read",
  resource
);

Conditional Permission

// Production deployments require MFA
permit(
  principal,
  action == Action::"deploy",
  resource in Environment::"production"
) when {
  context.mfa_verified == true
};

Deny Policy

// Forbid force deletion in production without emergency approval
forbid(
  principal,
  action == Action::"delete",
  resource in Environment::"production"
) when {
  context.force == true
} unless {
  context has approval_id &&
  context.approval_id.startsWith("EMERGENCY-")
};

Time-Based Restriction

// Production deployments only during business hours
forbid(
  principal,
  action == Action::"deploy",
  resource in Environment::"production"
) unless {
  context.time.split("T")[1].split(":")[0].decimal() >= 8 &&
  context.time.split("T")[1].split(":")[0].decimal() <= 18
};

IP Restriction

// Production access requires corporate network
forbid(
  principal,
  action in [Action::"create", Action::"delete", Action::"deploy"],
  resource in Environment::"production"
) unless {
  context.ip_address.startsWith("10.") ||
  context.ip_address.startsWith("172.16.") ||
  context.ip_address.startsWith("192.168.")
};

Context Variables

Authorization requests include context information:

AuthorizationContext {
    mfa_verified: bool,           // MFA verification status
    ip_address: String,           // Client IP address
    time: String,                 // ISO 8601 timestamp
    approval_id: Option<String>,  // Approval ID (optional)
    reason: Option<String>,       // Reason for operation (optional)
    force: bool,                  // Force flag
    additional: HashMap,          // Additional context
}

Entity Hierarchy

Environment (production, staging, development)
  ├── Workspace
  │   ├── Server
  │   ├── Taskserv
  │   ├── Cluster
  │   └── Workflow
  └── User/Team (principals)

Testing Policies

Using Cedar CLI

# Validate schema
cedar validate --schema schema.cedar --policies production.cedar

# Test specific authorization
cedar authorize \
  --policies production.cedar \
  --schema schema.cedar \
  --principal 'User::"user123"' \
  --action 'Action::"deploy"' \
  --resource 'Server::"server123"' \
  --context '{"mfa_verified": true}'

Using Rust Tests

cd provisioning/platform/orchestrator
cargo test security::tests

Policy Best Practices

1. Deny by Default

Cedar defaults to deny. Only explicitly permitted actions are allowed.

2. Use Schemas

Always define schemas for type safety and validation.

3. Explicit Context

Include all necessary context in authorization requests.

4. Separate by Environment

Different policies for production, staging, and development.

5. Version Control

All policies are in git for auditability and rollback.

6. Test Policies

Write tests for all policy scenarios.

7. Document Policies

Use annotations to explain policy intent:

@id("prod-deploy-mfa")
@description("All production deployments must have MFA verification")
permit(principal, action, resource) when { ... };

Hot Reload

The orchestrator watches this directory for changes and automatically reloads policies:

// Enable hot reload (default)
let config = PolicyLoaderConfigBuilder::new()
    .policy_dir("provisioning/config/cedar-policies")
    .hot_reload(true)
    .build();

Changes to policy files are picked up within seconds without restart.

Security Considerations

1. Secrets in Policies

Never hardcode secrets in policies. Use references:

// ❌ Bad
when { context.api_key == "secret123" }

// ✅ Good
when { context.api_key_hash == resource.expected_hash }

2. IP Restrictions

Use IP restrictions for sensitive operations:

when { context.ip_address.startsWith("10.") }

3. MFA Enforcement

Require MFA for critical operations:

when { context.mfa_verified == true }

4. Approval Workflows

Require approvals for production changes:

when { context has approval_id && context.approval_id != "" }

5. Rate Limiting

Cedar doesn't enforce rate limits directly. Implement in middleware:

// Hint: Implement rate limiting for critical operations
@id("rate-limit-critical")
permit(principal, action, resource) when { true };

Troubleshooting

Policy Validation Errors

Check policy syntax:

cedar validate --schema schema.cedar --policies production.cedar

Authorization Denied

Check diagnostics in authorization result:

let result = engine.authorize(&request).await?;
println!("Decision: {:?}", result.decision);
println!("Diagnostics: {:?}", result.diagnostics);
println!("Policies: {:?}", result.policies);

Hot Reload Not Working

Check file permissions and orchestrator logs:

tail -f provisioning/platform/orchestrator/data/orchestrator.log | grep -i policy

Additional Resources

• Cedar Documentation: https://docs.cedarpolicy.com/
• Cedar Playground: https://www.cedarpolicy.com/en/playground
• Implementation: provisioning/platform/orchestrator/src/security/
• Tests: provisioning/platform/orchestrator/src/security/tests.rs

Contributing

When adding new policies:

1. Update schema if adding new entities or actions
2. Add policy with annotations (@id, @description)
3. Write tests for new policy
4. Update this README
5. Validate with cedar validate
6. Create pull request with policy changes

Version History

Version	Date	Changes
1.0.0	2025-10-08	Initial Cedar policy implementation