AWS Cognito aws-auth: OAuth, PKCE, and Passkeys Guide

Quick answer

For a browser-based SPA or mobile app, choose an Amazon Cognito public app client with no client secret, use the OAuth 2.0 authorization code grant with PKCE, and create a new unpredictable code verifier for every authorization request. A passkey is a separate WebAuthn sign-in method; it does not replace PKCE, token validation, session controls, or API authorization.

The aws-auth skill can help configure and troubleshoot these layers, but the application must still implement the redirect, code exchange, token lifecycle, recovery experience, and protected-resource checks.

Separate the three decisions

Decision	What it protects	What it does not prove
Authorization code + PKCE	Binds code redemption to the client that started the flow	User presence, safe token storage, or API permission
Passkey / WebAuthn	Authenticates a user with a registered public-key credential	OAuth client binding or resource authorization
JWT validation and scopes	Lets a resource server evaluate token source and requested permission	Business-level permission for every object or tenant

Combining all three can produce a stronger path, but each needs its own configuration and tests.

Choose the app-client type first

Public client: SPA or mobile

A public client cannot protect a client secret. Configure no secret, register exact callback and sign-out URLs, use authorization code with PKCE, and request only necessary scopes. Do not fall back to the implicit grant for a new app.

Confidential client: server-side application

A backend capable of protecting credentials can use a client secret and an appropriate client-authentication method. Keep the secret out of browser bundles, mobile packages, logs, prompts, and generated examples.

Machine-to-machine client

Use the client-credentials grant for service-to-service access with custom resource-server scopes. This is not an end-user session and does not produce the same user identity context as interactive sign-in.

Build the PKCE path

1. Generate a cryptographically unpredictable code_verifier for the request.
2. Hash it with SHA-256 and base64url-encode the result as code_challenge.
3. Send the authorization request with response_type=code, the exact registered redirect URI, code_challenge, and code_challenge_method=S256.
4. Receive the authorization code at the redirect URI.
5. Redeem it at the token endpoint with the original verifier.
6. Validate the returned token set and establish the application session.

The verifier is request-specific. A static or predictable verifier defeats the binding. Use a maintained OIDC relying-party library where possible instead of hand-building protocol handling.

Add passkeys as an authentication choice

Amazon Cognito documents passkeys in its choice-based authentication flow. The current documentation says they are not available in the Lite feature plan. Managed login can handle the user-facing passkey flow, or an application backend can integrate the user-pools APIs.

Plan these details before enabling them:

• relying-party ID and the domain relationship;
• an existing authenticated session for enrollment;
• user-verification preference;
• recovery when a device or credential is unavailable;
• another allowed first factor where required by Cognito configuration;
• feature-plan, domain, and managed-login compatibility;
• enrollment, sign-in, deletion, and account-recovery tests.

Do not market “passwordless” as “account recovery no longer matters.” Recovery and credential lifecycle become more important, not less.

Review tokens and the protected API

An ID token describes authentication and user attributes. An access token carries authorization scopes and access context. A refresh token extends a session. Route each token only to the component that expects it.

For a protected request, verify the issuer, signature against the current JWKS, expiry, token use, audience or client identifier, and required scopes. Then apply application-specific tenant, ownership, and object checks. A valid token is necessary evidence, not a universal allow decision.

For API Gateway, the authorizer shape differs between HTTP APIs and REST APIs. The aws-auth skill covers the Cognito or JWT authorizer boundary; API routes, integrations, Lambda code, and fine-grained business authorization remain separate.

Agent review gates

Before allowing an agent to change production authentication:

• inventory the current app-client settings and require a full field diff;
• flag full-replacement CLI operations and preserve omitted fields;
• show account, Region, pool ID, client ID, domain, and callback scope;
• keep secrets and live tokens out of prompts and command output;
• test redirect mismatch, wrong verifier, wrong issuer, wrong audience, expiry, revocation, missing scope, and recovery;
• define rollback for domain, app-client, trigger, and token-lifecycle changes;
• require approval before writes that can interrupt active sessions.

Use the Cognito auth workflow planner to create a bounded review checklist. Read the aws-auth setup guide for installation and operational scope, or compare user pools and identity pools before adding AWS credentials to the client path.

Frequently asked questions

Should a browser or mobile Cognito app use PKCE?

For a public browser or mobile client, use the authorization code grant with PKCE and no client secret. Generate a new unpredictable verifier for each request and send its SHA-256 challenge at authorization.

Is a Cognito passkey the same as OAuth PKCE?

No. A passkey is a WebAuthn sign-in factor. PKCE binds an OAuth authorization request to the client that redeems the code. They protect different stages and can be used together.

Are Cognito passkeys available in every feature plan?

AWS documentation says passkeys are not available in the Lite plan and are part of choice-based authentication. Confirm the current plan and managed-login requirements before implementation.

Does aws-auth make token storage safe automatically?

No. The application still owns redirect handling, token storage, refresh behavior, logout, revocation, XSS defenses, issuer and audience checks, and backend scope enforcement.

Official sources

• AWS: using PKCE in authorization code grants
• AWS: authentication flows and passkeys
• AWS: managed login authentication methods
• AWS: token endpoint
• AWS: secure user-pool authentication flows

Source check: August 9, 2026. Verify current feature-plan gates, endpoint behavior, library guidance, limits, prices, and API shapes before production use.