Detailed OAuth2 + MCP Protocol Flow

oauth-macp.md

sequenceDiagram
    participant Enterprise as Enterprise User
    participant AI as AI Client<br/>(Claude/Inspector)
    participant APIGW as API Gateway
    participant OAuth2 as OAuth2 Proxy
    participant Auth as Lambda Authorizer
    participant Cognito as AWS Cognito
    participant MCP as MCP Server
    participant Data as Enterprise Data

    Note over Enterprise, Data: Complete Enterprise AI Integration Flow

    %% Discovery Phase
    rect rgb(240, 248, 255)
        Note over AI, OAuth2: 1. OAuth2 Discovery & Registration
        AI->>APIGW: GET /.well-known/openid-configuration
        APIGW->>OAuth2: Route to OAuth2 proxy
        OAuth2->>AI: OAuth2 metadata<br/>{issuer, endpoints, scopes, grant_types}
        
        AI->>APIGW: POST /oauth2/register<br/>{client_name, redirect_uris}
        APIGW->>OAuth2: Dynamic client registration
        OAuth2->>Cognito: CreateUserPoolClient<br/>(auto-detect public/confidential)
        Cognito->>OAuth2: {client_id, client_secret}
        OAuth2->>AI: Registration response<br/>{client_credentials, endpoints}
    end

    %% Authorization Phase
    rect rgb(255, 248, 240)
        Note over Enterprise, Cognito: 2. Enterprise User Authorization
        AI->>APIGW: GET /oauth2/authorize<br/>?client_id&redirect_uri&code_challenge
        APIGW->>OAuth2: Validate and redirect
        OAuth2->>AI: 302 Redirect to Cognito Hosted UI
        AI->>Enterprise: Open browser for authentication
        Enterprise->>Cognito: Login with enterprise credentials
        Note over Cognito: Enterprise SSO/MFA
        Cognito->>AI: 302 Redirect with authorization code
    end

    %% Token Exchange Phase
    rect rgb(255, 240, 245)
        Note over AI, OAuth2: 3. Token Exchange
        AI->>APIGW: POST /oauth2/token<br/>{code, code_verifier, client_credentials}
        APIGW->>OAuth2: Process token request
        OAuth2->>Cognito: Exchange code for enterprise tokens<br/>(with PKCE validation)
        Cognito->>OAuth2: {access_token, id_token, refresh_token}
        OAuth2->>AI: Enterprise token response
    end

    %% MCP Protocol Phase
    rect rgb(248, 255, 248)
        Note over AI, MCP: 4. MCP Session Establishment
        AI->>APIGW: POST /mcp<br/>Authorization: Bearer {enterprise_token}<br/>{method: "initialize", params: {clientInfo}}
        APIGW->>Auth: Validate enterprise token
        Auth->>Cognito: Verify JWT + enterprise claims
        Cognito->>Auth: Token valid + user context
        Auth->>APIGW: Allow + enterprise context
        APIGW->>MCP: Forward with enterprise auth
        MCP->>AI: {result: {serverInfo, capabilities}}
    end

    %% Tool Discovery Phase
    rect rgb(250, 245, 255)
        Note over AI, MCP: 5. Enterprise Tool Discovery
        AI->>APIGW: POST /mcp<br/>Authorization: Bearer {enterprise_token}<br/>{method: "tools/list"}
        APIGW->>Auth: Validate token (cached)
        Auth->>APIGW: Allow + cached context
        APIGW->>MCP: Forward authenticated request
        MCP->>AI: {result: {tools: [enterprise_tools_based_on_permissions]}}
    end

    %% Data Access Phase
    rect rgb(255, 250, 240)
        Note over AI, Data: 6. Secure Enterprise Data Access
        AI->>APIGW: POST /mcp<br/>Authorization: Bearer {enterprise_token}<br/>{method: "tools/call", params: {name: "query_data"}}
        APIGW->>Auth: Validate token (cached)
        Auth->>APIGW: Allow + enterprise context
        APIGW->>MCP: Forward with enterprise identity
        MCP->>Data: Query enterprise data<br/>Authorization: Bearer {same_enterprise_token}
        Data->>Cognito: Validate enterprise permissions
        Data->>MCP: Authorized enterprise data
        MCP->>AI: {result: {enterprise_insights}}
        
        Note over Enterprise: AI now has secure access<br/>to enterprise data with<br/>proper user permissions
    end

Loading