CloudFront Constructs

CDK constructs for deploying and protecting CloudFront distributions.

---

CloudfrontDistribution

A higher-level CloudFront distribution construct that simplifies certificate and WebACL wiring across AWS regions and optionally attaches the OIDC authorizer.

Region note: CloudfrontDistribution itself is region-agnostic and can be deployed to any AWS region. However, two dependencies must always reside in us-east-1:

• The ACM certificate (DNSValidatedCertificate) — required by CloudFront globally.
• The OIDCAuthorizerLambda construct, when OIDC authorization is enabled — Lambda@Edge functions must be deployed in us-east-1.

Both can be deployed in a separate us-east-1 stack and referenced by ARN or CloudFormation stack output name.

Key features:

• Accepts an ACM certificate as a DNSValidatedCertificate instance, a cross-region CloudFormation stack output name, or a raw ARN. The construct resolves cross-region ARNs automatically using StackOutputResolver.
• Creates Route 53 ALIAS records automatically when a hostedZone is provided for a domain name.
• Attaches a WAF WebACL when webAclArn is provided (cross-region resolution supported).
• Plugs in the OIDCAuthorizerLambda at the ViewerRequest lifecycle phase when oidcAuthorization is enabled. The authorizer can be applied to the default behavior, additional behaviors, or both.
• Forwards CloudFront access logs to the common log bucket when logging.enabled is true.

Notable props (CloudfrontDistributionProps):

Prop	Type	Description
certificate	DNSValidatedCertificate | string	ACM certificate (must be in us-east-1). Accepts an instance, a stack output name, or an ARN.
defaultBehavior	BehaviorOptions	Default CloudFront cache behavior.
additionalBehaviors	Record<string, BehaviorOptions>	Named additional behaviors. Key 'default' is reserved.
domains	CFDomain[]	Custom domain names and optional Route 53 hosted zones for automatic DNS records.
oidcAuthorization	OIDCAuthorization	Attach the OIDC authorizer. Set enabled: true and supply an OIDCAuthorizerLambda instance or its ARN.
webAclArn	string	WAF WebACL ARN or cross-region stack output name.
logging	CFLogging	Enable CloudFront access logging.
priceClass	PriceClass	CloudFront price class. Defaults to PRICE_CLASS_100.
defaultRootObject	string	Root object served for /. Defaults to index.html.

---

OIDCAuthorizerLambda

A Lambda@Edge construct that packages and deploys the OAuth 2.0 / OIDC authorization handler. It runs at the ViewerRequest phase and implements the full Authorization Code Flow with PKCE against any OIDC-compliant identity provider.

See edge-lambdas/lambda-src/oauth2-handler.md for a detailed description of the request flow and configuration options.

Props (OIDCAuthorizerLambdaProps):

Prop	Type	Description
oidcConfig	OAuthOptions	OIDC / OAuth 2.0 configuration (see below).
logLevel	ApplicationLogLevel	Lambda log level. Defaults to INFO.
timeout	Duration	Function timeout (1–5 seconds). Defaults to 5 seconds.

Outputs:

Property	Description
lambda	The underlying NodejsFunction.
logGroup	CloudWatch log group (created in us-east-1; logs replicate to edge regions).
edgeArn	Versioned Lambda ARN for use with CloudFront.
currentVersion	Current Lambda version.
functionArnExportName	CloudFormation export name of the function ARN, for cross-stack references.
hash	Source code hash; useful for detecting pending Lambda updates before deployment.

---

OAuthOptions (type)

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

Field	Type	Description
appDomainName	string	Public domain name of the CloudFront distribution (e.g. app.example.com).
clientId	string	OAuth 2.0 client ID used as the JWT audience claim.
wellKnownUri	string	OIDC discovery document URL (e.g. https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration).
scopes	string[]	OAuth scopes to request. Include openid and offline_access for OIDC + refresh tokens.
publicUriPrefixes	string[]	URI path prefixes that bypass authentication (e.g. ['/public/']).
authErrorPageUri	string	Path of the page shown on unrecoverable auth errors. Must be in publicUriPrefixes and registered with the IDP.
logoutRedirectUri	string	Path to redirect to after IDP logout. Set to '' to use the IDP's default logout page.
sessionValidity	number	Max-Age in seconds for the refresh token cookie (controls maximum session duration).

---

Example

// NOTE: The OIDCAuthorizer Lambda must be deployed to us-east-1 region, regardless of the region of
// the CloudFront distribution. If necessary, deploy this in a separate stack
const authLambda = new OIDCAuthorizerLambda(this, 'OIDCAuth', {
  oidcConfig: {
    appDomainName: 'app.example.com',
    clientId: '00000000-0000-0000-0000-000000000000',
    wellKnownUri: 'https://login.microsoftonline.com/<tenantId>/v2.0/.well-known/openid-configuration',
    scopes: ['openid', 'profile', 'offline_access'],
    publicUriPrefixes: ['/public/'],
    authErrorPageUri: '/public/auth-error.html',
    logoutRedirectUri: '/public/logout.html',
    sessionValidity: 60 * 60 * 8, // 8 hours
  },
})

new CloudfrontDistribution(this, 'Distribution', {
  certificate: myCertificate,
  defaultBehavior: { origin: myOrigin },
  domains: [{ name: 'app.example.com', hostedZone: myZone }],
  oidcAuthorization: {
    enabled: true,
    oidcAuthorizerLambda: authLambda,
  },
})
Copy