Copy page

MCP Authorization

MCP Auth0 OAuth Policy

Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Auth0.

This is an Auth0-friendly wrapper around McpOAuthInboundPolicy. Provide auth0Domain + clientId, and the OIDC issuer, JWKS URL, and Auth0 authorize/token URLs are derived automatically. For other identity providers, use McpOAuthInboundPolicy directly.

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

config/policies.json
{
  "name": "my-mcp-auth0-oauth-inbound-policy",
  "policyType": "mcp-auth0-oauth-inbound",
  "handler": {
    "export": "McpAuth0OAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "audience": "https://gateway.example.com",
      "auth0Domain": "my-tenant.us.auth0.com",
      "browserLoginOverrides": {
        "remoteTimeoutMs": 10000,
        "sessionTtlSeconds": 28800,
        "stateTtlSeconds": 900
      },
      "clientSecret": "$env(MCP_AUTH0_CLIENT_SECRET)",
      "gateway": {
        "accessTokenTtlSeconds": 900,
        "cimdEnabled": true,
        "refreshTokenTtlSeconds": 2592000
      },
      "scope": "openid profile email"
    }
  }
}

Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be mcp-auth0-oauth-inbound.
• handler.export <string> - The name of the exported type. Value should be McpAuth0OAuthInboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• auth0Domain (required) <string> - Your Auth0 tenant domain. The OIDC issuer, JWKS URL, /authorize URL, and /oauth/token URL are derived from this.
• audience <string> - Optional Auth0 API audience. When set, the gateway sends it as the Auth0 authorize?audience= parameter and validates returned provider access tokens against it. Leave unset when Auth0 is only used for browser identity.
• clientId (required) <string> - The Auth0 client_id registered for the gateway's browser login flow.
• clientSecret (required) <string> - The Auth0 client_secret. Use $env(...) to source from a secret environment variable.
• scope <string> - OIDC scopes requested during browser login. Defaults to "openid profile email".
• gateway <object> - Gateway-side OAuth token settings. The gateway issuer and advertised URLs are derived from the incoming request origin.
  • accessTokenTtlSeconds <integer> - Lifetime of access tokens issued by /oauth/token. Defaults to 900.
  • refreshTokenTtlSeconds <integer> - Lifetime of refresh tokens issued by /oauth/token. Defaults to 2592000.
  • cimdEnabled <boolean> - Whether to advertise client_id_metadata_document_supported in AS metadata. Defaults to true.
• idJag <undefined> - Optional Identity Assertion JWT Authorization Grant (ID-JAG / XAA) support for the gateway token endpoint.
• browserLoginOverrides <object> - Optional overrides for the derived browser-login settings.
  • remoteTimeoutMs <integer> - No description available. Defaults to 10000.
  • stateTtlSeconds <integer> - No description available. Defaults to 900.
  • sessionTtlSeconds <integer> - No description available. Defaults to 28800.

Using the Policy

MCP Auth0 OAuth Inbound

Authenticate MCP gateway requests using a gateway-issued OAuth access token, with browser login delegated to Auth0.

This is a thin Auth0-friendly wrapper around the generic McpOAuthInboundPolicy. Use it when you want to configure browser login with just auth0Domain + clientId + clientSecret instead of the full set of OIDC URLs.

Derived configuration

Given auth0Domain: "my-tenant.us.auth0.com", the wrapper derives:

Generic field	Derived value
oidc.issuer	https://my-tenant.us.auth0.com/
oidc.jwksUrl	https://my-tenant.us.auth0.com/.well-known/jwks.json
oidc.audience	the optional audience option
browserLogin.url	https://my-tenant.us.auth0.com/authorize
browserLogin.tokenUrl	https://my-tenant.us.auth0.com/oauth/token
browserLogin.audience	the optional audience option (omitted when unset)
browserLogin.clientId / clientSecret / scope	from policy options (clientSecret is required)

Leave audience unset when Auth0 is only used for browser identity. When set, the gateway passes it as Auth0's ?audience= parameter, so it must match an API/resource server identifier in the Auth0 tenant.

Configuration

Code
{
  "name": "auth0-managed-oauth",
  "policyType": "mcp-auth0-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime/mcp-gateway)",
    "export": "McpAuth0OAuthInboundPolicy",
    "options": {
      "auth0Domain": "$env(AUTH0_DOMAIN)",
      "clientId": "$env(AUTH0_CLIENT_ID)",
      "clientSecret": "$env(AUTH0_CLIENT_SECRET)"
    }
  }
}

auth0Domain is a bare hostname (my-tenant.us.auth0.com). The policy rejects values with http:// or https:// prefixes, or values without a dot.

Pairing

Pair this policy with McpTokenExchangeInboundPolicy and McpProxyHandler, the same as McpOAuthInboundPolicy. Only one MCP OAuth policy is allowed per project; attach the same policy by name to every MCP route.

Read more about how policies work