1  ---
  2  title: Authentication Proxy
  3  sidebar_position: 12
  4  ---
  5  
  6  # Authentication Proxy
  7  
  8  Gateway OAuth enables apps and gateways (like MCP) to authenticate via the OAuth2 service without registering separate redirect URIs with OAuth providers. Apps redirect directly to the auth server, which handles the OAuth flow and returns a gateway code that can be exchanged for tokens.
  9  
 10  
 11  ## How It Works
 12  
 13  High-level flow of the authentication proxy:
 14  
 15  ```mermaid
 16  graph TD
 17      D[MCP Client<br> e.g. Claude Code] --> A;
 18      A[MCP Server Gateway<br>port 8090] --> B;
 19      B[OAuth2 Service<br>port 8080] --> C;
 20      C[OAuth Provider] --> B;
 21      B --> A;
 22      A --> D;
 23      linkStyle 0 stroke-width:2px,fill:none,stroke:white;
 24      linkStyle 1 stroke-width:2px,fill:none,stroke:white;
 25      linkStyle 2 stroke-width:2px,fill:none,stroke:white;
 26      linkStyle 3 stroke-width:2px,fill:none,stroke:grey;
 27      linkStyle 4 stroke-width:2px,fill:none,stroke:grey;
 28      linkStyle 5 stroke-width:2px,fill:none,stroke:grey;
 29  ```
 30  
 31  
 32  Detailed sequence diagram of the OAuth2 authentication proxy flow:
 33  
 34  ```mermaid
 35  sequenceDiagram
 36      participant MC as MCP Client
 37      participant UB as User Browser
 38      participant AG as MCP Server Gateway
 39      participant AS as Auth Server (OAuth2)
 40      participant OP as OAuth Provider
 41  
 42      MC->>+AG: 1. GET /.well-known/oauth-authorization-server
 43      AG-->>-MC: 2. Returns auth address
 44  
 45      MC->>UB: 3. Opens browser at auth URL
 46      Note right of MC: Includes redirect_uri and code params
 47  
 48      UB->>+AG: 4. GET /oauth/authorize
 49      AG-->>-UB: 5. Redirect: /login?gateway_uri=...
 50  
 51      Note over UB, AS: User is redirected to Auth Server
 52      UB->>+AS: Follows redirect
 53      AS-->>-UB: 6. Redirect to OAuth Provider
 54  
 55      Note over UB, OP: User is redirected to OAuth Provider
 56      UB->>+OP: Follows redirect
 57      OP-->>-UB: 7. User authenticates & grants consent
 58  
 59      Note over OP, AS: Provider redirects back to Auth Server with auth code
 60      OP->>+AS: 8. Redirect: /callback?code=...
 61      
 62      AS->>+OP: 9. Exchange authorization code for tokens
 63      OP-->>-AS: Returns access_token, refresh_token
 64  
 65      Note over AS, UB: Auth Server creates a gateway code and redirects to App
 66      AS-->>-UB: 10. Redirect: /oauth/callback?code=GATEWAY_CODE
 67  
 68      Note over UB, AG: User is redirected back to the App Gateway
 69      UB->>+AG: Follows redirect with GATEWAY_CODE
 70      
 71      AG->>+AS: 11. Exchange gateway code for tokens
 72      AS-->>-AG: Returns access_token, refresh_token
 73      AG-->>MC: 12. Return access_token to client
 74  ```
 75  
 76  ## Configuration
 77  To enable the authentication proxy, add the following to your OAuth2 YAML configuration, usually named `oauth2_config.yaml`
 78  
 79  ```yaml
 80  # This enables apps to redirect through this auth server for OAuth
 81  proxy_oauth:
 82    enabled: true
 83    # Whitelist of allowed gateway callback URIs
 84    # Apps with URIs in this list can use this auth server for OAuth proxy
 85    allowed_redirect_uris:
 86      - "http://localhost:8090/oauth/callback"  # MCP gateway
 87      - "http://localhost:*"  # Wildcard for development - requires strict_uri_validation set to `false`
 88      - "https://mcp.example.com/oauth/callback"  # Production Example
 89  
 90    # Gateway code time-to-live in seconds (default: 300 = 5 minutes)
 91    # Codes expire after this time for security
 92    gateway_code_ttl_seconds: 300
 93  
 94    # URI validation mode (default: false = wildcard matching allowed)
 95    # Set to true for production to require exact URI matches
 96    strict_uri_validation: false
 97  ```
 98  
 99  Update `allowed_redirect_uris` with the actual callback URIs of your gateways.
100  
101  :::info
102  The path `/gateway-oauth` must be exposed and accessible in your deployment environment (e.g., Docker, Kubernetes) and it should point to the Auth Server service port.
103  :::
104  
105  ### Gateway Configuration
106  
107  In your MCP Gateway configuration YAML (e.g. `my-mcp-gateway.yaml`), update the `adapter` section to enable OAuth and point to the Auth Server:
108  
109  ```yaml
110  adapter_config:
111      enable_auth: ${OAUTH2_ENABLED}
112  
113      external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL, http://localhost:8080}
114      external_auth_provider: ${EXTERNAL_AUTH_PROVIDER, azure}
115  ```