Copy page

Authentication

JWT Auth Policy

The Open ID JWT Authentication policy allows you to authenticate incoming requests using an OpenID-compliant bearer token. It works with common authentication services like Auth0 but should also work with any valid OpenID JWT token.

When configured, Zuplo checks incoming requests for a JWT token and automatically populates the ZuploRequest's user property with a user object. This user object will have a sub property - taking the sub id from the JWT token. It will also have a data property populated by other data returned in the JWT token (including any claims).

With this policy, you'll benefit from:

• Universal Provider Support: Works with any OpenID-compliant identity provider including Auth0, Okta, Azure AD, and more
• Enhanced Security: Validate token signatures, expiration, and claims to ensure only authorized users access your API
• Flexible Configuration: Easily customize token sources, audience validation, and required claims
• Comprehensive User Context: Access user identity and claims directly in your request handlers
• Zero-Code Authentication: Implement industry-standard authentication with simple configuration
• Multiple Authentication Modes: Support both required and optional authentication patterns
• Seamless Integration: Works with your existing OpenID infrastructure with minimal setup

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.

Code
{
  "name": "my-open-id-jwt-auth-inbound-policy",
  "policyType": "open-id-jwt-auth-inbound",
  "handler": {
    "export": "OpenIdJwtInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "issuer": "$env(AUTH_ISSUER)",
      "audience": "$env(AUTH_AUDIENCE)",
      "jwkUrl": "https://my-tenant.us.auth0.com/.well-known/jwks.json"
    }
  }
}

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

• issuer <string> - The expected issuer claim in the JWT token.
• audience <string> - The expected audience claim in the JWT token.
• jwkUrl <string> - the url of the JSON Web Key Set (JWKS) - this is used to validate the JWT token signature (either this or secret must be set).
• secret <string> - The key used to verify the signature of the JWT token (either this or jwkUrl must be set).
• authHeader <string> - The name of the header with the key. Defaults to "Authorization".
• allowUnauthenticatedRequests <boolean> - indicates whether the request should continue if authentication fails. Defaults is false which means unauthenticated users will automatically receive a 401 response. Defaults to false.
• subPropertyName <string> - The name of the property in the JWT token that contains the user's unique identifier.
• headers <object> - Additional headers to send with the JWK request.
• 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

This policy authenticates incoming requests using OpenID-compliant JWT bearer tokens. It validates the token's signature, expiration, and claims against your OpenID provider's configuration.

Configuration

When setting up this policy, you'll need to configure your OpenID provider details. Note that sometimes the issuer and audience will vary between your environments (e.g. dev, staging and prod). We recommend storing these values in your environment variables and using $env(VARIABLE_NAME) to include them in your policy configuration.

Code
{
  "path": "/products/:123",
  "methods": ["POST"],
  "handler": {
    "module": "$import(./modules/products)",
    "export": "postProducts"
  },
  "corsPolicy": "None",
  "version": "none",
  "policies": {
    "inbound": ["your-jwt-policy-name"]
  }
}

Using the user property in code

After the policy validates a JWT token, it populates the ZuploRequest's user property with data from the token. You can access this in your request handlers:

Code
export async function myHandler(request: ZuploRequest, context: ZuploContext) {
  // Access the authenticated user information
  const userId = request.user?.sub;
  const userClaims = request.user?.data;

  // Use the user information in your business logic
  context.log.info(`Request from user: ${userId}`);

  // Continue processing
  return request;
}

For a complete example of using the user object in a RequestHandler, see Setting up JWT auth with Auth0.

OAuth 2.0 Protected Resource Metadata

The OpenID 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.

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

Read more about how policies work