AWS Cognito JWT Auth Policy

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

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-cognito-jwt-auth-inbound-policy",
  "policyType": "cognito-jwt-auth-inbound",
  "handler": {
    "export": "CognitoJwtInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false,
      "oAuthResourceMetadataEnabled": false,
      "region": "us-east-1",
      "userPoolId": "$env(AWS_COGNITO_USER_POOL_ID)"
    }
  }
}

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

• region (required) <string> - The AWS region where your Cognito instance is deployed.
• userPoolId (required) <string> - The user pool identifier.
• 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 Cognito 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