OAuth Authentication

Zuplo comes with build-in and extensible OAuth policies out of the box. These policies allow you to easily authenticate requests using popular services like Auth0, AWS Cognito, and more.

Some of the built-in policies are listed below.

• OpenId JWT Authentication Policy
• Auth0 JWT Authentication Policy
• Okta JWT Authentication Policy
• AWS Cognito JWT Authentication Policy

Request User

The OAuth policies will validate and decode the incoming JWT and add the data from the JWT. If the user is successfully authenticated the claims of their JWT access_token will be available on the request.user object.

The user's identifier (also known as the sub or subject) is available on the request.user.sub property. Other claims can be found on the request.user.data object as demonstrated below.

Code
async function (request: ZuploRequest, context: ZuploContext) {
  // Log the user's sub
  context.log.debug(`User ${request.user.sub} is authenticated`)

  // Check a custom claim
  if (request.user.data["orgId"] === "1234") {
    // do something
  }
}

Authorization Header

The built-in policies will validate the incoming JWT on the Authorization header. By default, the Authorization header will be left on the request and forwarded on to your backend.

It isn't recommended to validate the Access Token on both the gateway and the backend. However, by forwarding the header to the backend you can transition your API from doing authentication on your backend to authorizing at the Gateway. See this blog post for more details.

If you would like to remove the authorization header after you use one of the authorization policies, simply add the Remove Request Headers policy after the authorization policy and set it to remove the Authorization header.

OAuth 2.0 Protected Resource Metadata

OAuth clients, including MCP clients, discover how to obtain a token for your API through OAuth 2.0 Protected Resource Metadata (RFC 9728). Zuplo implements it in two parts:

• The OAuthProtectedResourcePlugin serves the metadata document at /.well-known/oauth-protected-resource and every path beneath it. The document lists your authorization servers, a human-readable resource name, and, when you set scopesSupported, the scopes clients should request.
• The oAuthResourceMetadataEnabled option on the JWT authentication policies makes the policy answer requests without a bearer token with a 401 response that carries a WWW-Authenticate header. The header's resource_metadata parameter points at the metadata document for that route, and its scope parameter repeats scopesSupported when the plugin sets it.

Code
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="mcp:access offline_access"

The MCP authorization specification requires clients to discover the authorization server this way, and tells them to take the scopes they request from the challenge first and from the metadata document second. Set scopesSupported whenever a policy protects an MCP server, so clients request the scopes your resource expects instead of every scope the authorization server advertises. See Advertising supported scopes for the full order of precedence and an Okta-specific pitfall.