Copy page

MCP Authorization

MCP Ping OAuth Policy

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

This is a PingOne-friendly wrapper around McpOAuthInboundPolicy. Provide a PingOne environmentId, or a PingOne customDomain, plus clientId and clientSecret; the PingOne 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.

config/policies.json
{
  "name": "my-mcp-ping-oauth-inbound-policy",
  "policyType": "mcp-ping-oauth-inbound",
  "handler": {
    "export": "McpPingOAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "browserLoginOverrides": {
        "remoteTimeoutMs": 10000,
        "sessionTtlSeconds": 28800,
        "stateTtlSeconds": 900
      },
      "clientId": "$env(PING_CLIENT_ID)",
      "clientSecret": "$env(PING_CLIENT_SECRET)",
      "customDomain": "login.example.com",
      "environmentId": "11111111-1111-4111-8111-111111111111",
      "gateway": {
        "accessTokenTtlSeconds": 900,
        "cimdEnabled": true,
        "refreshTokenTtlSeconds": 2592000
      },
      "region": "north-america",
      "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-ping-oauth-inbound.
• handler.export <string> - The name of the exported type. Value should be McpPingOAuthInboundPolicy.
• 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.

• environmentId <string> - The PingOne environment ID. Required unless customDomain is set.
• region <string> - The PingOne geography for the environment. Ignored when customDomain is set. Allowed values are north-america, canada, europe, singapore, australia, asia-pacific. Defaults to "north-america".
• customDomain <string> - Optional PingOne custom domain, without https://, a trailing slash, or a path. When set, environmentId and region are not used.
• clientId (required) <string> - The PingOne OIDC application client_id registered for the gateway's browser login flow.
• clientSecret (required) <string> - The PingOne OIDC application 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.
• 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 Ping OAuth Inbound

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

This is a thin PingOne-friendly wrapper around the generic McpOAuthInboundPolicy. Use it when you want to configure browser login with a PingOne environment ID and OAuth client credentials instead of the full set of OIDC URLs.

Derived configuration

For PingOne regional domains, provide environmentId and optional region. The default region is north-america, which uses auth.pingone.com.

Generic field	Derived value
oidc.issuer	https://auth.pingone.com/{environmentId}/as
oidc.jwksUrl	https://auth.pingone.com/{environmentId}/as/jwks
browserLogin.url	https://auth.pingone.com/{environmentId}/as/authorize
browserLogin.tokenUrl	https://auth.pingone.com/{environmentId}/as/token
browserLogin.clientId / clientSecret / scope	from policy options (clientSecret is required)

Set region to one of north-america, canada, europe, singapore, australia, or asia-pacific to use the corresponding PingOne auth domain.

If your PingOne environment uses a custom domain, set customDomain instead of environmentId and region. The policy derives endpoints from https://{customDomain}/as.

This policy is for PingOne cloud. PingFederate deployments can customize issuer hosts, issuer paths, endpoint paths, and metadata templates; use McpOAuthInboundPolicy for PingFederate.

Configuration

Code
{
  "name": "ping-managed-oauth",
  "policyType": "mcp-ping-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime)",
    "export": "McpPingOAuthInboundPolicy",
    "options": {
      "environmentId": "$env(PING_ENVIRONMENT_ID)",
      "region": "north-america",
      "clientId": "$env(PING_CLIENT_ID)",
      "clientSecret": "$env(PING_CLIENT_SECRET)"
    }
  }
}

For a custom domain:

Code
{
  "name": "ping-managed-oauth",
  "policyType": "mcp-ping-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime)",
    "export": "McpPingOAuthInboundPolicy",
    "options": {
      "customDomain": "login.example.com",
      "clientId": "$env(PING_CLIENT_ID)",
      "clientSecret": "$env(PING_CLIENT_SECRET)"
    }
  }
}

environmentId must be a PingOne environment UUID, such as 11111111-1111-4111-8111-111111111111. Do not pass the PingOne issuer URL, auth domain, or client ID in this field.

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