design

Design Document

Overview

The AdminUI Cedarling Authorization system implements a Cedar-based fine-grained authorization framework that provides role-based access control (RBAC) with granular permissions. The system uses Amazon's Cedar policy language to define and evaluate authorization policies in real-time, ensuring secure access to Admin UI resources.

The architecture follows a layered approach with clear separation between policy management, authorization evaluation, and application integration. The system supports six primary roles (Admin, Identity Manager, Security Auditor, Developer, Support Staff, End User) with specific permissions across eleven resource types.

Architecture

High-Level Architecture

graph TB
    subgraph "Admin UI Application Layer"
        UI[Admin UI Components]
        API[REST API Endpoints]
    end
    
    subgraph "Authorization Layer"
        AuthMiddleware[Authorization Middleware]
        AuthService[Authorization Service]
        PolicyEvaluator[Cedar Policy Evaluator]
    end
    
    subgraph "Policy Management Layer"
        PolicyStore[Policy Store]
        PolicyManager[Policy Manager]
        SchemaValidator[Schema Validator]
    end
    
    subgraph "Data Layer"
        PolicyDB[(Policy Database)]
        AuditDB[(Audit Log Database)]
        ConfigDB[(Configuration Database)]
    end
    
    UI --> API
    API --> AuthMiddleware
    AuthMiddleware --> AuthService
    AuthService --> PolicyEvaluator
    PolicyEvaluator --> PolicyStore
    PolicyManager --> PolicyStore
    PolicyStore --> PolicyDB
    AuthService --> AuditDB
    SchemaValidator --> ConfigDB

Loading

Authorization Flow

sequenceDiagram
    participant Client
    participant AuthMiddleware
    participant AuthService
    participant PolicyEvaluator
    participant PolicyStore
    participant AuditLogger
    
    Client->>AuthMiddleware: Request with JWT token
    AuthMiddleware->>AuthService: Extract principal & context
    AuthService->>PolicyEvaluator: Evaluate(principal, action, resource)
    PolicyEvaluator->>PolicyStore: Get applicable policies
    PolicyStore-->>PolicyEvaluator: Return policies
    PolicyEvaluator-->>AuthService: Authorization decision
    AuthService->>AuditLogger: Log decision
    AuthService-->>AuthMiddleware: Permit/Deny
    AuthMiddleware-->>Client: Allow request or 403 Forbidden

Loading

Components and Interfaces

1. Authorization Service

Purpose: Central service for authorization decisions and policy evaluation coordination.

Key Methods:

interface AuthorizationService {
  authorize(request: AuthorizationRequest): Promise<AuthorizationResult>
  batchAuthorize(requests: AuthorizationRequest[]): Promise<AuthorizationResult[]>
  validatePrincipal(principal: Principal): Promise<boolean>
}

interface AuthorizationRequest {
  principal: Principal
  action: string
  resource: Resource
  context?: Record<string, any>
}

interface AuthorizationResult {
  decision: 'PERMIT' | 'DENY'
  reason?: string
  policies?: string[]
  errors?: string[]
}

2. Cedar Policy Evaluator

Purpose: Wrapper around Cedar policy engine for policy evaluation.

Key Methods:

interface CedarPolicyEvaluator {
  evaluate(principal: Principal, action: string, resource: Resource, context?: Context): Promise<Decision>
  validatePolicy(policy: string): Promise<ValidationResult>
  loadPolicies(policies: Policy[]): Promise<void>
}

interface Decision {
  decision: 'PERMIT' | 'DENY'
  diagnostics: Diagnostic[]
}

3. Policy Store

Purpose: Manages storage and retrieval of Cedar policies and schema.

Key Methods:

interface PolicyStore {
  createPolicy(policy: Policy): Promise<string>
  updatePolicy(id: string, policy: Policy): Promise<void>
  deletePolicy(id: string): Promise<void>
  getPolicy(id: string): Promise<Policy>
  getAllPolicies(): Promise<Policy[]>
  getPoliciesForPrincipal(principal: Principal): Promise<Policy[]>
}

4. Authorization Middleware

Purpose: HTTP middleware that intercepts requests and enforces authorization.

Key Methods:

interface AuthorizationMiddleware {
  authorize(req: Request, res: Response, next: NextFunction): Promise<void>
  extractPrincipal(token: string): Promise<Principal>
  buildAuthorizationRequest(req: Request, principal: Principal): AuthorizationRequest
}

5. Policy Manager

Purpose: Administrative interface for managing policies and roles.

Key Methods:

interface PolicyManager {
  createRole(role: Role): Promise<void>
  assignRoleToUser(userId: string, roleId: string): Promise<void>
  createPolicyFromTemplate(template: PolicyTemplate, params: Record<string, any>): Promise<Policy>
  validatePolicySet(): Promise<ValidationResult[]>
}

6. Audit Logger

Purpose: Logs all authorization decisions and security events.

Key Methods:

interface AuditLogger {
  logAuthorizationDecision(request: AuthorizationRequest, result: AuthorizationResult): Promise<void>
  logPolicyChange(action: string, policyId: string, userId: string): Promise<void>
  logSecurityEvent(event: SecurityEvent): Promise<void>
  queryAuditLogs(filter: AuditFilter): Promise<AuditLog[]>
}

Data Models

Principal Model

interface Principal {
  id: string
  type: 'User' | 'Service'
  roles: string[]
  attributes: Record<string, any>
}

Resource Model

interface Resource {
  type: ResourceType
  id: string
  attributes: Record<string, any>
  parent?: Resource
}

type ResourceType = 
  | 'AuthServer'
  | 'User' 
  | 'OAuthClient'
  | 'CustomScripts'
  | 'SMTPConfig'
  | 'SAMLConfig'
  | 'AuditLog'
  | 'Scope'
  | 'Assets'
  | 'ConfigAPI'
  | 'Role'
  | 'Profile'

Policy Model

interface Policy {
  id: string
  name: string
  description?: string
  effect: 'PERMIT' | 'FORBID'
  principal: string
  action: string[]
  resource: string
  conditions?: string[]
  createdAt: Date
  updatedAt: Date
  version: number
}

Cedar Schema

namespace AdminUI {
  entity User = {
    "id": String,
    "email": String,
    "roles": Set<String>
  };
  
  entity Role = {
    "name": String,
    "permissions": Set<String>
  };
  
  entity AuthServer = {
    "id": String,
    "config": Record
  };
  
  entity OAuthClient = {
    "id": String,
    "clientId": String,
    "redirectUris": Set<String>
  };
  
  entity CustomScripts = {
    "id": String,
    "scriptType": String,
    "enabled": Bool
  };
  
  entity AuditLog = {
    "id": String,
    "timestamp": String,
    "event": String
  };
  
  entity Profile = {
    "userId": String,
    "email": String,
    "name": String
  };
}

Error Handling

Error Types

1. Policy Evaluation Errors: Invalid policy syntax, missing entities
2. Authorization Errors: Access denied, invalid principal
3. System Errors: Database connectivity, service unavailability
4. Validation Errors: Invalid request format, missing required fields

Error Response Format

interface ErrorResponse {
  error: {
    code: string
    message: string
    details?: Record<string, any>
    timestamp: string
    requestId: string
  }
}

Error Handling Strategy

• Fail Secure: Default to DENY when errors occur
• Graceful Degradation: Log errors and continue with safe defaults
• Circuit Breaker: Prevent cascade failures in policy evaluation
• Retry Logic: Automatic retry for transient failures

Testing Strategy

Unit Testing

• Policy Evaluation Tests: Test Cedar policy evaluation with various inputs
• Service Layer Tests: Mock dependencies and test business logic
• Middleware Tests: Test request interception and authorization flow
• Data Layer Tests: Test policy storage and retrieval operations

Integration Testing

• End-to-End Authorization Flow: Test complete request-to-response cycle
• Policy Management Workflow: Test policy CRUD operations
• Multi-Role Scenarios: Test complex permission combinations
• Error Scenarios: Test error handling and recovery

Performance Testing

• Policy Evaluation Latency: Measure authorization decision time
• Concurrent Request Handling: Test system under load
• Policy Store Performance: Test large policy set handling
• Memory Usage: Monitor resource consumption

Security Testing

• Permission Bypass Attempts: Test for authorization vulnerabilities
• Policy Injection: Test for policy manipulation attacks
• Token Validation: Test JWT token security
• Audit Trail Integrity: Verify logging completeness

Test Data Management

• Policy Test Sets: Predefined policies for different scenarios
• User Role Combinations: Test users with various role assignments
• Resource Hierarchies: Test nested resource permissions
• Edge Cases: Boundary conditions and error states

Automated Testing Pipeline

• Pre-commit Hooks: Run unit tests before code commits
• CI/CD Integration: Automated test execution on builds
• Security Scans: Automated vulnerability assessment
• Performance Benchmarks: Continuous performance monitoring