Skip to main content

Slack Bot Authorization Architecture

Pulled from PR #975 for spec 093 (093-agent-enterprise-identity).

This document provides a visual reference for the end-to-end authorization flow when a user interacts with CAIPE through Slack. It covers the trust chain from Okta enterprise SSO through Slack, Keycloak token exchange, CAIPE orchestration, and user scope validation at every boundary.

For the full design rationale and implementation details, see Enterprise Identity Federation.

Authorization Topology​

The following diagram shows every actor in the authorization chain, the trust relationships between them, and what credentials or tokens flow across each boundary.

Trust Boundaries​

BoundaryProtocolTrust MechanismWhat Crosses
Okta → Slack AppSAML 2.0 / OIDCSAML assertionAuthenticated user session
Okta → KeycloakOIDCSigned tokensid_token, groups, email
Slack App → Bot BackendWebSocket (Socket Mode)Slack-signed payloads (HMAC-SHA256)user_id, team_id, message
Bot Backend → KeycloakHTTPSClient credentials + signed JWT assertionslack_user_id claim
Keycloak → Bot BackendHTTPSSigned Keycloak access tokensub, groups, scope, act
Bot Backend → OrchestratorA2A Protocol (message/stream)Bearer token (user JWT)User token + request payload
Orchestrator → KeycloakHTTPSOBO token exchangeParent token + requested scope
Orchestrator → AgentsA2A / internalNarrowed token + task payloadScoped JWT + task context
Agent → KeycloakHTTPSToken exchange (requested_issuer)Narrowed token → external token
Agent → DownstreamHTTPSProvider-specific auth (OAuth, API key, JWT)User's own credentials

Pre-Authorization: User Identity Binding​

Before any runtime authorization can happen, the user must complete a one-time identity binding that links their Slack identity to a Keycloak account (backed by Okta SSO). This is analogous to how Deno apps pre-authorize with Keycloak — the user proves who they are once, and all subsequent interactions are frictionless.

This step creates a permanent mapping: slack_user_id ↔ keycloak_sub ↔ okta_uid.

What the Binding Enables​

Once bound, the Bot Backend can perform RFC 8693 token exchanges on every subsequent interaction without any user involvement:

Service Connector Pre-Authorization​

Beyond identity binding, users can also pre-authorize downstream service connectors (GitHub, Jira, PagerDuty, etc.) through the CAIPE UI Connections page or via Slack commands. Each connector follows a similar one-time OAuth consent pattern:

Runtime Authorization Sequence​

After pre-authorization is complete, this sequence diagram traces a single user message from Slack through every authorization gate at runtime. No user interaction is required — the Bot Backend resolves identity and obtains tokens automatically.

Scope Validation Gates​

Every authorization boundary enforces scope validation. This flowchart shows the decision logic at each gate and what happens when validation fails.

Token Lifecycle & Scope Narrowing​

This diagram visualizes how the token transforms as it flows through the CAIPE authorization chain — showing scope reduction, TTL shortening, and delegation chain growth at each hop.

Scope Reduction Guarantee​

User Token scope:     github  jira  argocd  pagerduty    (4 services)
                         ↓
GitHub Agent scope:   github:repo:read  github:pr:write   (2 fine-grained)
                         ↓
Service Token:        repo  read:org                       (GitHub-native scopes)

At every exchange, Keycloak enforces: requested scope ⊆ parent scope. Scope can only narrow, never widen. An agent that holds github:repo:read cannot request github:repo:write — the exchange fails with 403.

Multi-Agent Scope Isolation​

When the orchestrator routes a user request to multiple agents, each agent receives an independently scoped token. A compromised agent token cannot access services beyond its granted scope.

JWT Delegation Chain (Audit Trail)​

The act (actor) claim in each JWT records the full delegation chain, providing a complete audit trail from the original user through every intermediary.

Every action taken by a CAIPE agent is attributable to the human user who initiated it. The delegation chain is embedded in the JWT and logged at every boundary for forensic traceability.

Error Handling & Recovery Flows​

When authorization fails at any gate, the system responds with specific recovery actions rather than generic errors.