provisioning/config/cedar-policies/QUICK_REFERENCE.md

Cedar Authorization Quick Reference

Version: 1.0.0 | Date: 2025-10-08

---

📋 Quick Stats

Metric	Value
Total Policy Lines	889 lines
Rust Code Lines	2,498 lines
Policy Files	4 files (schema + 3 policies)
Test Cases	30+ tests
Actions Supported	11 actions
Resource Types	7 resource types
Team Types	5 teams

---

🎯 Policy Files

File	Lines	Purpose
schema.cedar	221	Entity/action definitions
production.cedar	224	Production policies (strict)
development.cedar	213	Development policies (relaxed)
admin.cedar	231	Administrative policies

---

🔐 Key Production Policies

Policy ID	Description	Enforced
prod-deploy-mfa	MFA required for deployments	✅
prod-deploy-approval	Approval required for deployments	✅
prod-deploy-hours	Business hours only (08:00-18:00 UTC)	✅
prod-delete-mfa	MFA required for deletions	✅
prod-delete-no-force	No force deletion without emergency approval	❌
prod-ip-restriction	Corporate network only	✅
prod-ssh-restricted	SSH limited to platform-admin/SRE	✅
prod-cluster-admin-only	Only platform-admin manages clusters	✅

---

👥 Team Permissions

Team	Production	Staging	Development
platform-admin	Full access	Full access	Full access
sre	Deploy, rollback, SSH (with approval)	Deploy, rollback	Full access
developers	Read-only	Deploy (with approval)	Full access
audit	Read-only	Read-only	Read-only
security	Read-only + lockdown	Read-only + lockdown	Read-only

---

🛠️ Actions

Action	Description	Example Resource
create	Create new resources	Server, Cluster, Workspace
delete	Delete resources	Server, Taskserv, Workflow
update	Modify existing resources	Server, Cluster
read	Read resource details	Server, Taskserv
list	List all resources	Servers, Clusters
deploy	Deploy infrastructure	Server, Taskserv, Cluster
rollback	Rollback deployments	Server, Taskserv
ssh	SSH access	Server
execute	Execute workflows	Workflow
monitor	View monitoring data	Server, Cluster
admin	Administrative operations	All resources

---

📦 Resources

Resource	Fields	Example
Server	id, hostname, workspace, environment	prod-web-01
Taskserv	id, name, workspace, environment	kubernetes, postgres
Cluster	id, name, workspace, environment, node_count	k8s-cluster (3 nodes)
Workspace	id, name, environment, owner_id	production-workspace
Workflow	id, workflow_type, workspace, environment	deployment-workflow
User	id, email, username, teams	user@example.com
Team	id, name	platform-admin, developers

---

🧩 Context Variables

Variable	Type	Required	Example
mfa_verified	bool	✅	true
ip_address	string	✅	10.0.0.1
time	string (ISO 8601)	✅	2025-10-08T14:30:00Z
approval_id	string	❌	APPROVAL-12345
reason	string	❌	Emergency hotfix
force	bool	❌	true
ssh_key_fingerprint	string	❌ (SSH only)	SHA256:abc123...

---

💻 Usage Examples

Basic Authorization Check

use provisioning_orchestrator::security::{
    CedarEngine, AuthorizationRequest, Principal, Action, Resource, AuthorizationContext
};

let request = AuthorizationRequest {
    principal: Principal::User {
        id: "user123".to_string(),
        email: "user@example.com".to_string(),
        username: "developer".to_string(),
        teams: vec!["developers".to_string()],
    },
    action: Action::Deploy,
    resource: Resource::Server {
        id: "server123".to_string(),
        hostname: "prod-web-01".to_string(),
        workspace: "production".to_string(),
        environment: "production".to_string(),
    },
    context: AuthorizationContext {
        mfa_verified: true,
        ip_address: "10.0.0.1".to_string(),
        time: "2025-10-08T14:30:00Z".to_string(),
        approval_id: Some("APPROVAL-12345".to_string()),
        reason: None,
        force: false,
        additional: HashMap::new(),
    },
};

let result = engine.authorize(&request).await?;
match result.decision {
    AuthorizationDecision::Allow => println!("✅ Authorized"),
    AuthorizationDecision::Deny => println!("❌ Denied: {:?}", result.diagnostics),
}

Load Policies with Hot Reload

use provisioning_orchestrator::security::{CedarEngine, PolicyLoader, PolicyLoaderConfigBuilder};
use std::sync::Arc;

let engine = Arc::new(CedarEngine::new());

let config = PolicyLoaderConfigBuilder::new()
    .policy_dir("provisioning/config/cedar-policies")
    .hot_reload(true)
    .schema_file("schema.cedar")
    .add_policy_file("production.cedar")
    .add_policy_file("development.cedar")
    .add_policy_file("admin.cedar")
    .build();

let mut loader = PolicyLoader::new(config, engine.clone());
loader.load().await?;
loader.start_hot_reload()?;

Axum Middleware Integration

use axum::{Router, routing::post, middleware};
use provisioning_orchestrator::security::{SecurityContext, auth_middleware};

let public_key = std::fs::read("keys/public.pem")?;
let security = Arc::new(
    SecurityContext::new(&public_key, "control-center", "orchestrator")?
        .with_cedar(engine.clone())
);

let app = Router::new()
    .route("/servers", post(create_server))
    .layer(middleware::from_fn_with_state(security.clone(), auth_middleware));

---

🧪 Testing

Run All Tests

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

Validate Policies

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

Test Specific Authorization

cedar authorize \
    --policies production.cedar \
    --schema schema.cedar \
    --principal 'Provisioning::User::"user123"' \
    --action 'Provisioning::Action::"deploy"' \
    --resource 'Provisioning::Server::"server123"' \
    --context '{"mfa_verified": true, "ip_address": "10.0.0.1", "time": "2025-10-08T14:00:00Z"}'

---

📊 Decision Matrix

Scenario	Principal	Action	Resource	MFA	Approval	Decision
Dev creates dev server	developers	create	dev server	❌	❌	✅ ALLOW
Dev deploys to prod	developers	deploy	prod server	✅	✅	❌ DENY (read-only)
SRE deploys to prod	sre	deploy	prod server	✅	✅	✅ ALLOW
Admin deploys to prod	platform-admin	deploy	prod server	❌	❌	✅ ALLOW
Audit reads prod	audit	read	prod server	❌	❌	✅ ALLOW
Audit deletes prod	audit	delete	prod server	✅	✅	❌ DENY (forbid)
SRE SSH to prod	sre	ssh	prod server	❌	❌	✅ ALLOW
Dev SSH to prod	developers	ssh	prod server	❌	❌	❌ DENY

---

🔥 Common Scenarios

Emergency Production Deployment

Required:

• Principal: platform-admin or sre
• MFA: ✅ Verified
• Approval: EMERGENCY-* prefix
• IP: Corporate network

Example:

context: AuthorizationContext {
    mfa_verified: true,
    approval_id: Some("EMERGENCY-OUTAGE-2025-10-08".to_string()),
    ip_address: "10.0.0.5".to_string(),
    time: "2025-10-08T22:30:00Z".to_string(),  // Outside business hours OK with emergency
    // ...
}

Developer Self-Service

Allowed in Development:

• Create/delete servers
• Deploy without approval
• Force deletion
• Unlimited SSH access

Not Allowed:

• Cluster size > 5 nodes
• Modify other users' workspaces

Audit Compliance

Audit Team:

• ✅ Read all resources (all environments)
• ✅ Monitor all systems
• ❌ Cannot modify anything
• ❌ Cannot deploy or delete

---

📖 Cedar Syntax Quick Reference

Basic Permit

permit(principal, action, resource);

Conditional Permit

permit(principal, action, resource) when {
    context.mfa_verified == true
};

Forbid Policy

forbid(principal, action, resource) when {
    context.force == true
};

Unless Clause

forbid(principal, action, resource) unless {
    context.approval_id.startsWith("EMERGENCY-")
};

Team Membership

permit(
    principal in Team::"developers",
    action,
    resource
);

Resource Hierarchy

permit(
    principal,
    action,
    resource in Environment::"production"
);

---

🚨 Security Best Practices

1. Always Validate MFA for production operations
2. Require Approvals for destructive operations
3. IP Restrictions for production access
4. Time Windows for maintenance operations
5. Audit Logging for all authorization decisions
6. Version Control all policy files
7. Test Policies before deploying to production
8. Emergency Access only with proper approvals

---

🔧 Troubleshooting

Always Denied?

1. Check if policies loaded: engine.policy_stats().await
2. Verify context: println!("{:#?}", request.context)
3. Check diagnostics: println!("{:?}", result.diagnostics)
4. Validate entity types match schema

Hot Reload Not Working?

1. Check file permissions
2. View logs: tail -f orchestrator.log | grep -i policy
3. Verify hot_reload: true in config

MFA Not Enforced?

1. Ensure context.mfa_verified == true
2. Check production policies loaded
3. Verify resource.environment == "production"

---

📚 Resources

• Full Documentation: docs/architecture/CEDAR_AUTHORIZATION_IMPLEMENTATION.md
• Cedar Docs: 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

---

Last Updated: 2025-10-08