# MCP Auth0 OAuth Inbound 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.

```json title="config/policies.json"
{
  "name": "my-mcp-auth0-oauth-inbound-policy",
  "policyType": "mcp-auth0-oauth-inbound",
  "handler": {
    "export": "McpAuth0OAuthInboundPolicy",
    "module": "$import(@zuplo/runtime/mcp-gateway)",
    "options": {
      "auth0Domain": "$env(AUTH0_DOMAIN)",
      "clientId": "$env(AUTH0_CLIENT_ID)",
      "clientSecret": "$env(AUTH0_CLIENT_SECRET)"
    }
  }
}
```

### Policy Configuration

- `name` <code className="text-green-600">&lt;string&gt;</code> - The name of your policy instance. This is used as a reference in your routes.
- `policyType` <code className="text-green-600">&lt;string&gt;</code> - The identifier of the policy. This is used by the Zuplo UI. Value should be `mcp-auth0-oauth-inbound`.
- `handler.export` <code className="text-green-600">&lt;string&gt;</code> - The name of the exported type. Value should be `McpAuth0OAuthInboundPolicy`.
- `handler.module` <code className="text-green-600">&lt;string&gt;</code> - The module containing the policy. Value should be `$import(@zuplo/runtime/mcp-gateway)`.
- `handler.options` <code className="text-green-600">&lt;object&gt;</code> - The options for this policy. [See Policy Options](#policy-options) below.

### Policy Options

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

- `auth0Domain` **(required)** <code className="text-green-600">&lt;string&gt;</code> - Your Auth0 tenant domain. The OIDC issuer, JWKS URL, /authorize URL, and /oauth/token URL are derived from this.
- `audience` <code className="text-green-600">&lt;string&gt;</code> - 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)** <code className="text-green-600">&lt;string&gt;</code> - The Auth0 client_id registered for the gateway's browser login flow.
- `clientSecret` **(required)** <code className="text-green-600">&lt;string&gt;</code> - The Auth0 client_secret. Use $env(...) to source from a secret environment variable.
- `scope` <code className="text-green-600">&lt;string&gt;</code> - OIDC scopes requested during browser login. Defaults to `"openid profile email"`.
- `gateway` <code className="text-green-600">&lt;object&gt;</code> - Gateway-side OAuth token settings. The gateway issuer and advertised URLs are derived from the incoming request origin.
  - `accessTokenTtlSeconds` <code className="text-green-600">&lt;integer&gt;</code> - Lifetime of access tokens issued by /oauth/token. Defaults to `900`.
  - `refreshTokenTtlSeconds` <code className="text-green-600">&lt;integer&gt;</code> - Lifetime of refresh tokens issued by /oauth/token. Defaults to `2592000`.
  - `cimdEnabled` <code className="text-green-600">&lt;boolean&gt;</code> - Whether to advertise client_id_metadata_document_supported in AS metadata. Defaults to `true`.
- `browserLoginOverrides` <code className="text-green-600">&lt;object&gt;</code> - Optional overrides for the derived browser-login settings.
  - `remoteTimeoutMs` <code className="text-green-600">&lt;integer&gt;</code> - No description available. Defaults to `10000`.
  - `stateTtlSeconds` <code className="text-green-600">&lt;integer&gt;</code> - No description available. Defaults to `900`.
  - `sessionTtlSeconds` <code className="text-green-600">&lt;integer&gt;</code> - 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.

## Pairing

Pair this policy with `McpTokenExchangeInboundPolicy` and `McpProxyHandler`, the
same as `McpOAuthInboundPolicy`.

Read more about [how policies work](/articles/policies)