API Gateway Constructs

CDK constructs for protecting Amazon API Gateway APIs.

`OIDCAuthorizerLambda`

A construct that packages and deploys a Lambda TOKEN authorizer for API Gateway. It validates the OAuth 2.0 / OIDC access_token presented in the request's Authorization header against any OIDC-compliant identity provider and returns an IAM policy that allows or denies the invocation.

See lambda-src/apigw-oauth2-handler.md for a detailed description of the validation flow and configuration options.

Key features:

Verifies the JWT access_token signature against the IDP's JWKS endpoint (RS256) and validates the audience (aud) and issuer (iss) claims.
Discovers the IDP's jwks_uri and issuer automatically from the .well-known/openid-configuration document.
Caches the OIDC configuration and JWKS client between invocations to minimise IDP round-trips on warm containers.
Returns a stage-wide wildcard policy on success. Because API Gateway caches a TOKEN authorizer result per token across all methods, scoping the policy to a single method ARN would cause the cached policy to be rejected on other methods invoked with the same token.
Injects a message into the authorizer context describing why a request was allowed or denied.

Props (OIDCAuthorizerLambdaProps):

Prop	Type	Description
`oidcConfig`	`OAuthOptions`	OIDC / OAuth 2.0 configuration (see below).
`timeout`	`Duration`	Function timeout (1–5 seconds). Defaults to 5 seconds.
`environment`	`string`	Optional suffix appended to the Lambda function name (e.g. `dev`, `prod`).
`logLevel`	`ApplicationLogLevel`	Lambda log level. Defaults to `INFO`. Use `DEBUG` only in test — it logs tokens.

Outputs:

Property	Description
`lambda`	The underlying `NodejsFunction`. Attach it to a `TokenAuthorizer`.

`OAuthOptions` (type)

Configuration type for the OIDC authorizer. All fields are injected into the Lambda as environment variables at build time.

Field	Type	Description
`clientId`	`string`	OAuth 2.0 client ID. Always accepted as an audience (`aud`) claim value. For MS Entra ID this is the Enterprise App ID of the OIDC configuration.
`wellKnownUri`	`string`	OIDC discovery document URL (e.g. `https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration`).
`audience`	`string[]`	Additional accepted `aud` claim values. Extends the default — `clientId` is always accepted. Defaults to `[clientId]`.
`issuer`	`string[]`	Additional accepted `iss` claim values, merged with the issuer read from the well-known endpoint. May be required when the IDP uses a different issuer for the `access_token` (e.g. `https://sts.windows.net/{tenantId}/` for MS Entra ID).

Example

import { TokenAuthorizer } from 'aws-cdk-lib/aws-apigateway'
import { OIDCAuthorizerLambda } from 'cdk-constructs-lib/apigw'

const authorizer = new OIDCAuthorizerLambda(this, 'OIDCAuth', {
  oidcConfig: {
    clientId: '00000000-0000-0000-0000-000000000000',
    wellKnownUri: 'https://login.microsoftonline.com/<tenantId>/v2.0/.well-known/openid-configuration',
    // Optional: MS Entra ID access tokens use a different issuer than the well-known document
    issuer: ['https://sts.windows.net/<tenantId>/'],
  },
  environment: 'prod',
})

const tokenAuthorizer = new TokenAuthorizer(this, 'ApiAuthorizer', {
  handler: authorizer.lambda,
})

// Attach to a method / integration
myResource.addMethod('GET', myIntegration, {
  authorizer: tokenAuthorizer,
})

API Gateway Constructs

`OIDCAuthorizerLambda`

`OAuthOptions` (type)

Example

Settings

On This Page

API Gateway Constructs

OIDCAuthorizerLambda

OAuthOptions (type)

Example

Settings

On This Page

`OIDCAuthorizerLambda`

`OAuthOptions` (type)