Okta JWT Auth Policy

Authenticate requests with JWT tokens issued by Okta. This is a customized version of the OpenId JWT Policy specifically for Okta.

See this document for more information about OAuth authorization in Zuplo.

Configuration

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

config/policies.json
{
  "name": "my-okta-jwt-auth-inbound-policy",
  "policyType": "okta-jwt-auth-inbound",
  "handler": {
    "export": "OktaJwtInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false,
      "audience": "api://my-api",
      "issuerUrl": "https://dev-12345.okta.com/oauth2/abc",
      "oAuthResourceMetadataEnabled": false
    }
  }
}

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 okta-jwt-auth-inbound.
handler.export <string> - The name of the exported type. Value should be OktaJwtInboundPolicy.
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.

issuerUrl (required) <string> - Your Okta authorization server's issuer URL. For example, https://dev-12345.okta.com/oauth2/abc.
audience <string> - The Okta audience of your API, for example api://my-api.
allowUnauthenticatedRequests <boolean> - Allow unauthenticated requests to proceed. This is use useful if you want to use multiple authentication policies or if you want to allow both authenticated and non-authenticated traffic. Defaults to false.
oAuthResourceMetadataEnabled <boolean> - Enables OAuth 2.0 Protected Resource Metadata discovery (RFC 9728). When true, requests without a bearer token receive a 401 whose WWW-Authenticate header points resource_metadata at the /.well-known/oauth-protected-resource document for the request path and, when the OAuthProtectedResourcePlugin declares scopesSupported, lists those scopes in scope. Requires the OAuthProtectedResourcePlugin in zuplo.runtime.ts or a user-defined route at that path. Defaults to false.

Using the Policy

OAuth 2.0 Protected Resource Metadata

The Okta JWT Auth policy supports OAuth protected resource metadata discovery. To enable this feature, set the oAuthResourceMetadataEnabled option to true and add the OAuthProtectedResourcePlugin to modules/zuplo.runtime.ts. When configured, this enables OAuth clients to find metadata information about how to interact with your OAuth 2.0 protected resources according to RFC 9728.

When the plugin is configured with scopesSupported, the 401 response also lists those scopes in the scope parameter of its WWW-Authenticate header, so MCP clients request exactly the scopes your resource expects instead of every scope the authorization server advertises.

Okta custom authorization servers always advertise the device_sso and interclient_access scopes in their own metadata and reject authorization requests that combine them with your scopes (illegal_scope_combination). Set scopesSupported on the plugin when this policy protects an MCP server, so clients never fall back to that list.

See this document for more information about OAuth authorization in Zuplo.