# MCP Okta OAuth Policy

:::note{title="MCP Gateway Policy"}

This policy is for use with the [MCP Gateway](/mcp-gateway/introduction). See
the MCP Gateway documentation to learn how to proxy and secure MCP servers with
Zuplo.

:::

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

This is an Okta-friendly wrapper around `McpOAuthInboundPolicy`. Provide an Okta
domain, optional authorization server id, `clientId`, and `clientSecret`; the
Okta OIDC issuer, JWKS URL, and browser login endpoints are derived
automatically.

## Configuration

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

```json title="config/policies.json"
{
  "name": "my-mcp-okta-oauth-inbound-policy",
  "policyType": "mcp-okta-oauth-inbound",
  "handler": {
    "export": "McpOktaOAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "authorizationServerId": "default",
      "browserLoginOverrides": {
        "remoteTimeoutMs": 10000,
        "sessionTtlSeconds": 28800,
        "stateTtlSeconds": 900
      },
      "clientId": "$env(OKTA_CLIENT_ID)",
      "clientSecret": "$env(OKTA_CLIENT_SECRET)",
      "gateway": {
        "accessTokenTtlSeconds": 900,
        "cimdEnabled": true,
        "refreshTokenTtlSeconds": 2592000
      },
      "oktaDomain": "acme.okta.com",
      "scope": "openid profile email"
    }
  }
}
```

### 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-okta-oauth-inbound`.
- `handler.export` <code className="text-green-600">&lt;string&gt;</code> - The name of the exported type. Value should be `McpOktaOAuthInboundPolicy`.
- `handler.module` <code className="text-green-600">&lt;string&gt;</code> - The module containing the policy. Value should be `$import(@zuplo/runtime)`.
- `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.

- `oktaDomain` **(required)** <code className="text-green-600">&lt;string&gt;</code> - The Okta org domain, without https://, a trailing slash, or a path.
- `authorizationServerId` <code className="text-green-600">&lt;string&gt;</code> - Optional Okta custom authorization server id. Omit this to use the org authorization server.
- `clientId` **(required)** <code className="text-green-600">&lt;string&gt;</code> - The Okta OIDC application client_id registered for the gateway's browser login flow.
- `clientSecret` **(required)** <code className="text-green-600">&lt;string&gt;</code> - The Okta OIDC application 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 Okta OAuth Inbound

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

This is a thin Okta-friendly wrapper around the generic `McpOAuthInboundPolicy`.
Use it when you want to configure browser login with Okta-specific fields
instead of the full set of OIDC URLs.

## Derived configuration

For the Okta org authorization server, the wrapper derives:

| Generic field           | Derived value                              |
| ----------------------- | ------------------------------------------ |
| `oidc.issuer`           | `https://{oktaDomain}`                     |
| `oidc.jwksUrl`          | `https://{oktaDomain}/oauth2/v1/keys`      |
| `browserLogin.url`      | `https://{oktaDomain}/oauth2/v1/authorize` |
| `browserLogin.tokenUrl` | `https://{oktaDomain}/oauth2/v1/token`     |

When `authorizationServerId` is set, the wrapper derives custom authorization
server URLs:

| Generic field           | Derived value                                                      |
| ----------------------- | ------------------------------------------------------------------ |
| `oidc.issuer`           | `https://{oktaDomain}/oauth2/{authorizationServerId}`              |
| `oidc.jwksUrl`          | `https://{oktaDomain}/oauth2/{authorizationServerId}/v1/keys`      |
| `browserLogin.url`      | `https://{oktaDomain}/oauth2/{authorizationServerId}/v1/authorize` |
| `browserLogin.tokenUrl` | `https://{oktaDomain}/oauth2/{authorizationServerId}/v1/token`     |

These endpoint shapes follow Okta's org and custom authorization server metadata
conventions.

## Configuration

```json
{
  "name": "okta-managed-oauth",
  "policyType": "mcp-okta-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime)",
    "export": "McpOktaOAuthInboundPolicy",
    "options": {
      "oktaDomain": "acme.okta.com",
      "authorizationServerId": "default",
      "clientId": "$env(OKTA_CLIENT_ID)",
      "clientSecret": "$env(OKTA_CLIENT_SECRET)"
    }
  }
}
```

`oktaDomain` must be an Okta org domain like `acme.okta.com` or
`acme.oktapreview.com`. Do not include `https://`, a trailing slash, or an
authorization server path.

## 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](/articles/policies)