OAuth mode

OAuth mode is an authentication option for service accounts where the MCP server validates tokens using JSON Web Key Set (JWKS) from an external OAuth or OpenID Connect provider. This mode is designed for enterprise deployments that require integration with identity providers and support for separate service account and user tokens.

{
  "service_account": {
    "enabled": true,
    "mode": "oauth",
    "header": "X-OEMCP-SERVICEACCOUNT",
    "prefix": "Bearer ",
    "issuer": "https://auth.example.com/realms/myapp",
    "jwks_uri": "https://auth.example.com/realms/myapp/certs",
    "algorithms": ["RS256"],
    "required_scopes": ["service.access"]
  },
  "user_auth": {
    "enabled": true,
    "header": "Authorization",
    "prefix": "Bearer "
  }
}

OAuth authentication modes

OAuth-based authentication provides flexibility for integrating MCP with external identity providers and enabling Single Sign-On. These modes allow secure token validation and forwarding to downstream APIs.

OAuth2 endpoints and metadata

When authentication fails, the MCP server provides additional metadata in the response to guide clients in obtaining valid credentials. If require_metadata_on_401=true, which is the default value, all 401 responses include a WWW-Authenticate header with the Bearer realm and a resource_metadata parameter pointing to the protected resource metadata endpoint. This helps clients discover the correct OAuth configuration.

OAuth2 authentication patterns

PKCE flow for secure OAuth2 authentication

The MCP server implements the OAuth2 authorization code flow with Proof Key for Code Exchange (PKCE) to secure authentication for public clients such as browser-based MCP clients. PKCE adds cryptographic proof to prevent interception attacks by ensuring that the client initiating the authorization request is the same client exchanging the authorization code for tokens.

The sequence diagram shows the steps involved in the PKCE flow, including discovery, authorization, callback, token exchange, backend exchange, and API calls. It highlights how the MCP client and MCP server interact with the identity provider to complete the OAuth2 Authorization Code flow securely.

Token exchange pattern for PAS for OpenEdge integration

The MCP server uses token exchange to integrate with Progress Application Server (PAS) for OpenEdge back-end systems. Token exchange allows the server to replace an inbound user token with a PAS for OpenEdge-scoped token that has different claims, a shorter lifetime, and limited scopes. This approach enforces the principle of least privilege and improves security for downstream API calls.

The sequence diagram shows the steps involved in token exchange pattern flow:

{
  "service_account": {
    "enabled": true,
    "mode": "token",
    "header": "X-OEMCP-SERVICEACCOUNT",
    "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
    "required_scopes": ["mcp_access"]
  },
  "user_auth": {
    "enabled": true,
    "mode": "token", 
    "header": "Authorization",
    "prefix": "Bearer ",
    "token_exchange": {
      "enabled": true,
      "url": "https://pasoe-server.example.com:8810/oeabl/web/identity/token",
      "method": "POST",
      "timeout_ms": 5000,
      "headers": {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": {
          "env": "TOKEN_EXCHANGE_LOGIN_TOKEN",
          "prefix": "OECP "
        }
      },
      "body": {
        "mode": "json",
        "field": "token",
        "include_prefix": false
      },
      "response": {
        "type": "json",
        "json_path": "access_token"
      }
    }
  }
}