MCP OAuth Architecture

Reference Sequence

sequenceDiagram
  participant MCP as Local MCP
  participant ID as IdentityGatewayService
  participant User as End User
  participant Browser as Browser Session
  participant Broker as BrokerService

  MCP->>ID: BeginMcpOauthDeviceAuthorization
  ID-->>MCP: device_code, user_code, verification_uri
  User->>Browser: Login + consent
  Browser->>ID: ApproveMcpOauthDeviceAuthorization
  MCP->>ID: ExchangeMcpOauthDeviceAuthorization (poll)
  ID-->>MCP: success + scoped broker token
  MCP->>Broker: lease create/redeem/revoke (+ request_proof)

Token and State Model

Device auth state:
  status: authorization_pending | approved | success | access_denied | expired_token
  ttl: default 10m (min 1m, max 15m)

Broker token:
  principal: user:{uid}
  binding: tenant_id + pop_key_id + selector scopes
  ttl: default 10m (max 15m)

• No static API keys for local MCP login.
• Approval endpoint remains authenticated.
• Exchange returns terminal statuses for denied/expired flows.
• Scopes are selector-bound to exact credential targets.
• Token exchange conveys authorization context only, not plaintext vault key material.