🧭 Epic

Title: Enhanced IAM Pre-Tool Plugin with Rich Context Authorization

Goal: Extend the IAM pre-tool plugin to support rich context authorization (ABAC), human-in-the-loop approval workflows, and non-MCP server tools (REST endpoints).

Why now:

• Current plugin framework supports basic RBAC but lacks fine-grained attribute-based access control (ABAC)
• Enterprise deployments need human approval for sensitive operations (financial transfers, data deletion)
• REST tools (non-MCP) need the same authorization controls as MCP tools
• Compliance requirements (SOX, SOC2) mandate approval workflows for certain operations

📖 User Stories

Scenario: Authorize based on user department
  Given the IAM plugin is configured with ABAC rules
  And user "alice" has department="engineering"
  When alice invokes tool "deploy_to_production"
  And the tool requires department="devops" OR department="sre"
  Then the tool invocation should be denied
  And an audit log entry should be created

Scenario: Authorize based on resource sensitivity
  Given the IAM plugin is configured with data classification rules
  And resource "customer_database" has classification="confidential"
  When user "bob" with clearance="public" invokes tool "query_database"
  Then the tool invocation should be denied
  And the denial reason should indicate clearance mismatch

Scenario: Authorize based on time window
  Given the IAM plugin is configured with time-based rules
  And tool "batch_delete" is only allowed during maintenance windows
  When user invokes "batch_delete" outside the maintenance window
  Then the tool invocation should be denied
  And the response should include next allowed time window

Scenario: Tool requires approval before execution
  Given the IAM plugin is configured to require approval for "wire_transfer"
  When user invokes "wire_transfer" with amount > $10,000
  Then the tool invocation should be paused
  And an approval request should be created
  And the user should receive a pending status

Scenario: Approver approves the request
  Given a pending approval request for "wire_transfer"
  And user "manager" is designated approver
  When "manager" approves the request
  Then the tool invocation should proceed
  And the approval should be recorded in audit trail

Scenario: Approval timeout
  Given a pending approval request
  And the approval timeout is 1 hour
  When 1 hour passes without approval
  Then the request should be automatically denied
  And the user should be notified of timeout

Scenario: REST tool invocation authorized
  Given a REST tool "api/v1/users" is registered
  And the IAM plugin is configured with REST tool policies
  When user invokes the REST tool via gateway
  Then the IAM plugin should evaluate authorization
  And authorized requests should proceed to the REST endpoint

Scenario: REST tool invocation denied
  Given a REST tool "api/v1/admin/delete" requires admin role
  And user "viewer" has role="viewer"
  When "viewer" invokes the REST tool
  Then the request should be denied with 403 status
  And the denial should be logged

Scenario: Mixed MCP and REST authorization
  Given a virtual server with both MCP and REST tools
  When the IAM plugin evaluates authorization
  Then the same policy engine should be used for both
  And audit logs should capture both tool types

🏗 Architecture

Rich Context Authorization Flow

sequenceDiagram
    participant Client
    participant Gateway
    participant IAMPlugin
    participant PolicyEngine
    participant ToolService
    
    Client->>Gateway: tools/call (wire_transfer, amount=50000)
    Gateway->>IAMPlugin: tool_pre_invoke hook
    
    IAMPlugin->>IAMPlugin: Extract user attributes
    IAMPlugin->>IAMPlugin: Extract resource attributes
    IAMPlugin->>IAMPlugin: Get environmental context
    
    IAMPlugin->>PolicyEngine: Evaluate ABAC policy
    PolicyEngine-->>IAMPlugin: Decision + obligations
    
    alt Requires Approval
        IAMPlugin->>IAMPlugin: Create approval request
        IAMPlugin-->>Gateway: Pending (elicitation)
        Gateway-->>Client: Approval required
    else Authorized
        IAMPlugin-->>Gateway: Continue
        Gateway->>ToolService: Execute tool
    else Denied
        IAMPlugin-->>Gateway: Deny with reason
        Gateway-->>Client: 403 Forbidden
    end

ABAC Context Model

classDiagram
    class AuthorizationContext {
        +subject: SubjectAttributes
        +resource: ResourceAttributes
        +action: ActionAttributes
        +environment: EnvironmentAttributes
    }
    
    class SubjectAttributes {
        +user_id: str
        +roles: list[str]
        +department: str
        +clearance_level: str
        +groups: list[str]
    }
    
    class ResourceAttributes {
        +tool_name: str
        +classification: str
        +owner: str
        +tags: list[str]
    }
    
    class ActionAttributes {
        +operation: str
        +parameters: dict
    }
    
    class EnvironmentAttributes {
        +timestamp: datetime
        +ip_address: str
        +is_maintenance_window: bool
    }
    
    AuthorizationContext --> SubjectAttributes
    AuthorizationContext --> ResourceAttributes
    AuthorizationContext --> ActionAttributes
    AuthorizationContext --> EnvironmentAttributes

📋 Implementation Tasks

Phase 1: Rich Context Foundation

• Extend GlobalContext with user attributes (department, groups, clearance)
• Add resource attributes to tool metadata schema
• Create AuthorizationContext model for ABAC evaluation
• Add environmental context (time, IP, maintenance windows)

Phase 2: ABAC Policy Integration

• Extend Cedar plugin to support ABAC attributes
• Extend OPA plugin to support ABAC attributes
• Create policy templates for common ABAC scenarios
• Add policy validation and testing tools

Phase 3: Human-in-the-Loop Approval

• Create approval request storage (database table)
• Implement approval workflow state machine
• Integrate with MCP elicitation for approval prompts
• Add approver notification webhooks
• Implement approval timeout handling

Phase 4: REST Tool Support

• Hook IAM plugin into REST tool invocation path
• Extract user context from HTTP headers
• Apply policy evaluation to REST tools
• Ensure consistent audit logging

Phase 5: Admin UI

• Add approval queue UI for approvers
• Add ABAC policy editor
• Add audit trail viewer with ABAC details

Phase 6: Testing

• Unit tests for ABAC evaluation
• Unit tests for approval workflows
• Integration tests for REST tool authorization
• Performance tests for policy evaluation

⚙️ Configuration Examples

ABAC Policy (Cedar format)

permit (
    principal in Group::"engineering",
    action == Action::"invoke",
    resource == Tool::"deploy_to_staging"
) when {
    context.environment.is_business_hours == true
};

forbid (
    principal,
    action == Action::"invoke", 
    resource == Tool::"wire_transfer"
) unless {
    resource.amount < 10000 ||
    context.approval.status == "approved"
};

Approval Workflow Configuration

iam_plugin:
  approval_workflows:
    - name: high_value_transfer
      trigger:
        tool_pattern: "wire_transfer|bank_transfer"
        conditions:
          - field: "amount"
            operator: ">"
            value: 10000
      approvers:
        - role: "finance_manager"
        - role: "compliance_officer"
      require_all: false  # Any approver can approve
      timeout_minutes: 60
      notification:
        webhook: "https://slack.webhook.url"

✅ Success Criteria

• ABAC policies can reference user department, groups, clearance
• ABAC policies can reference resource classification, tags
• Time-based authorization rules work correctly
• Approval workflows pause tool execution until approved
• Approval timeouts automatically deny requests
• REST tools subject to same authorization as MCP tools
• Audit logs capture ABAC context and approval decisions
• Performance: policy evaluation < 10ms for 95th percentile

🏁 Definition of Done

• GlobalContext extended with user attributes
• AuthorizationContext model implemented
• Cedar/OPA plugins support ABAC attributes
• Approval workflow implemented with storage
• Elicitation integration for approvals works
• REST tool authorization implemented
• Admin UI for approval queue
• Unit tests for all new functionality
• Integration tests pass
• Documentation updated
• Code passes make verify
• PR reviewed and approved

🔗 Related Issues

• [FEATURE][AUTH]: Propagate end user identity and context through the CF workflow #1436 - Propagate end user identity through CF workflow
• [EPIC][PLUGIN]: Per-virtual-server plugin selection with multi-level RBAC #1247 - Per-virtual-server plugin selection
• Cedar Policy Plugin
• OPA Policy Plugin

📓 Additional Context

Compliance Requirements Addressed

• SOX: Separation of duties for financial operations
• SOC2: Access control logging and approval workflows
• HIPAA: Data classification-based access control
• GDPR: Purpose limitation through context-aware authorization