OAuth 2.0 CloudFront Edge Lambda Handler

A Lambda@Edge viewer-request handler that protects a CloudFront distribution by enforcing authentication via the OAuth 2.0 Authorization Code Flow with PKCE (RFC 7636). It is designed to work with any OpenID Connect (OIDC)-compliant identity provider and has been specifically tested with Microsoft Entra ID (Azure AD) v2.0.

How it works

The handler intercepts every viewer request to the CloudFront distribution before it reaches the origin. Depending on the request URI and the presence of session cookies, it either passes the request through to the origin or performs one of the OAuth operations described below.

Request flow

sequenceDiagram
    actor Browser
    participant CF as CloudFront<br/>(Lambda@Edge)
    participant IDP as Identity Provider<br/>(Entra ID)
    participant Origin

    Note over Browser,Origin: 1 — First visit (no session)
    Browser->>CF: GET /protected-page
    CF-->>Browser: 302 → IDP /authorize<br/>(PKCE code_challenge, state, nonce)<br/>Set-Cookie: state, nonce, code_verifier (10 min)
    Browser->>IDP: GET /authorize (user logs in)
    IDP-->>Browser: 302 → /callback?code=…&state=…
    Browser->>CF: GET /callback?code=…&state=…<br/>Cookie: state, nonce, code_verifier
    CF->>IDP: POST /token (code + code_verifier)
    IDP-->>CF: access_token, refresh_token, id_token
    Note over CF: Validate state (CSRF) and nonce (replay)
    CF-->>Browser: 302 → /<br/>Set-Cookie: access_token, refresh_token<br/>Clear: state, nonce, code_verifier

    Note over Browser,Origin: 2 — Authenticated request (valid token)
    Browser->>CF: GET /protected-page<br/>Cookie: access_token, refresh_token
    Note over CF: Verify JWT (JWKS, audience, issuer, expiry)
    CF->>Origin: Forwarded request
    Origin-->>CF: Response
    CF-->>Browser: Response

    Note over Browser,Origin: 3 — Expired access token (refresh)
    Browser->>CF: GET /protected-page<br/>Cookie: access_token (expired), refresh_token
    CF->>IDP: POST /token (grant_type=refresh_token)
    IDP-->>CF: New access_token, refresh_token
    CF-->>Browser: 302 → /protected-page<br/>Set-Cookie: new access_token, refresh_token

    Note over Browser,Origin: 4 — Logout
    Browser->>CF: GET /logout<br/>Cookie: access_token
    Note over CF: Decode access_token → extract login_hint claim
    CF-->>Browser: 302 → IDP /logout?logout_hint=…<br/>Clear: access_token, refresh_token

Request routing

Login flow (step by step)

1. Unauthenticated request arrives → handler generates a random state, nonce, and a PKCE code_verifier/code_challenge pair.
2. The browser is redirected to the IDP's authorization_endpoint with the PKCE and OIDC parameters.
3. state, nonce, and code_verifier are stored as short-lived (10 min) HttpOnly; Secure; SameSite=Lax cookies.
4. The IDP authenticates the user and redirects back to https://{appDomainName}/callback?code=…&state=….
5. The handler validates the state against the cookie (CSRF protection), exchanges the code at the token_endpoint, and verifies the nonce inside the returned id_token (replay protection).
6. On success, access_token and refresh_token cookies are set and the user is redirected to /.

Token verification

Access tokens are verified on every authenticated request using the IDP's published JWKS (jwks_uri from the OIDC discovery document). Verification checks:

• Signature (RS256)
• Audience: clientId plus any values in opts.audience
• Issuer: issuer from the OIDC config plus any values in opts.issuer
• Expiry

The id_token is verified only at callback time to validate the nonce claim (replay protection). Its issuer and audience are always validated strictly against the values from the OIDC discovery document (config.issuer) and clientId respectively — the opts.issuer and opts.audience extensions do not apply to id_token validation. This is intentional: id_token claims are defined by the OIDC spec and should not vary, whereas access_token claims differ between providers and token versions (see Microsoft Entra ID notes below).

Caching

The OIDC well-known config and the JWKS client are cached in memory (default TTL: 60 minutes) to minimise latency on the Lambda@Edge 5-second budget. The parsed configuration options are also cached to avoid re-parsing the build-time-injected string literals on every invocation.

Configuration

Because Lambda@Edge does not support environment variables, all configuration values are injected at build time by ESBuild, which replaces #PLACEHOLDER# tokens in the source with real values. In practice you pass the values to the CDK construct that builds and deploys the Lambda, and the construct handles the substitution.

OAuthOptions

IDP registration requirements

The following URIs must be registered as Redirect URIs in the IDP application registration:

• https://{appDomainName}/callback — authorization code callback
• {authErrorPageUri} — auth error page (if configured)
• {logoutRedirectUri} — post-logout redirect (if configured)

Microsoft Entra ID notes

Entra ID issues two structurally different access_token formats depending on the app registration configuration:

When using v1 access tokens (the default for most tenants), you must set opts.issuer to the STS issuer URL, otherwise every access_token verification call will fail with an issuer mismatch.

The id_token issuer is always https://login.microsoftonline.com/{tenantId}/v2.0 regardless of the access token version, and is validated strictly against the OIDC discovery document — opts.issuer has no effect on id_token validation.

Logout hint

At /logout, the handler decodes the access_token cookie (without re-verifying the signature, as the token is about to be discarded) and reads the login_hint claim. If present, it is passed to the IDP's end_session_endpoint as logout_hint. For Entra ID this suppresses the "Are you sure you want to sign out?" confirmation page and the Home Realm Discovery prompt, providing a seamless logout experience.

The login_hint claim is the preferred_username (UPN/email) of the authenticated user. Entra ID includes it in access_tokens by default when the v2 token endpoint is used. If the claim is absent (e.g. guest accounts, service principals, or v1 tokens), the IDP logout page is shown without a hint — the logout itself still succeeds.

Session cookies

All cookies are set with Secure; HttpOnly; SameSite=Lax; Domain={appDomainName}.

Error handling

The handler uses a layered fallback strategy to ensure the user always receives a usable response even when the IDP is unreachable:

1. Known auth errors (state mismatch, nonce mismatch, token exchange failure) → redirect to authErrorPageUri.
2. Unexpected errors during token verification → attempt a clean IDP logout with authErrorPageUri as the post-logout redirect, so the IDP clears its own session.
3. IDP logout itself fails (e.g. network issue) → fall back directly to getRedirectToAuthErrorPage, which clears all local cookies.
4. Top-level unhandled errors (e.g. OIDC config fetch fails on startup) → same two-step fallback as above.

All fetch calls use an AbortController with a timeout derived from the Lambda's remaining execution time minus a 500 ms grace period, preventing the handler from hanging until the Lambda hard timeout.