aws-auth

name: aws-auth description: > Adds user authentication to web and mobile apps with Amazon Cognito (user pools and identity pools) and the AWS Amplify client auth libraries. Covers sign-up/sign-in flows and the login page (Cognito-hosted UI / managed login), MFA, password policies, OAuth 2.0 / OIDC flows (auth-code + PKCE, client credentials), social/SAML federation, tokens (ID/access/refresh, rotation, revocation, storage), Cognito Lambda triggers, identity pools (temp AWS creds), and gating API Gateway (or ALB) routes to signed-in users via Cognito/JWT authorizers. Applies when adding a login or sign-up page, configuring a user pool or app client, choosing user pool vs identity pool, wiring social/SAML, refreshing tokens, requiring sign-in on an API Gateway or ALB, or debugging redirect_uri/token/MFA/CORS/federation errors. Does NOT cover Amplify Gen2 backend definitions (defineAuth, npx ampx → aws-amplify), IAM/STS/Identity Center (→ aws-iam), or API Gateway/Lambda resource config beyond the authorizer (→ aws-serverless). metadata: version: "1"

AWS Auth (Amazon Cognito)

Application-level user authentication and authorization with Amazon Cognito and the Amplify client auth libraries. Verify specific limits, quotas, and exact API shapes against official AWS documentation when precision matters; trust the docs over memory when they conflict.

Recommended: The AWS MCP server provides streamlined access to the AWS APIs used in this skill (Cognito user pool/app client/identity pool setup, API Gateway authorizers). If it is unavailable, the AWS CLI commands shown throughout work directly — the skill has no hard dependency on MCP.

When NOT to use: Amplify Gen2 backend code (defineAuth, amplify/auth.ts, npx ampx); IAM policy/role/trust-policy authoring, STS, or IAM Identity Center console SSO; API Gateway route/integration setup or Lambda function implementation (this skill covers only the Cognito/JWT authorizer configuration and the purpose of Cognito Lambda triggers).

User Pool vs Identity Pool — pick first

These are different services that are frequently confused. Most apps need a user pool; add an identity pool only if the client must call AWS services directly.

If your app only calls your own backend/API, you do not need an identity pool — send the user pool token to your API. See identity-pools.md.

Critical Warnings

update-user-pool-client and set-identity-pool-roles are FULL REPLACE, not partial updates: Any field you omit is reset to its default — calling update-user-pool-client with only the fields you want to change silently wipes ExplicitAuthFlows, token validity, EnableTokenRevocation, refresh-token rotation, and read/write attributes; set-identity-pool-roles likewise replaces the whole roles + RoleMappings structure. Always read-modify-write: describe-user-pool-client (or get-identity-pool-roles) first, then re-send every existing field plus your change. In an agent context the wipe is invisible — the call succeeds and only breaks later when a user hits the missing flow. See managed-login-oauth.md and identity-pools.md.

Don't use the implicit grant for new apps: The implicit grant (response_type=token) is legacy and returns tokens in the URL fragment. Use the authorization code grant with PKCE (response_type=code + code_challenge) for SPAs and mobile — public clients, no client secret. See managed-login-oauth.md.

Don't store refresh tokens in localStorage for high-value apps: localStorage is readable by any injected script (XSS). The Amplify client library defaults to localStorage; switch to cookieStorage, keep refresh-token lifetime short, and enable refresh token rotation + token revocation on the app client. See tokens-and-sessions.md.

Access-token claim customization needs a paid feature plan: The pre token generation trigger customizes the ID token on the entry-level plan (V1), but customizing the access token (V2/V3) requires a paid feature plan — check the Cognito feature plans documentation for which plan currently includes this, as plan names and inclusions can change. Don't assume access-token claims work on the entry-level plan. See lambda-triggers.md.

App client secret + SPA = broken auth: A public client (browser/mobile) must have no client secret. If a secret is set, token calls fail unless a SECRET_HASH is sent, which a browser cannot protect. Generate a secret only for confidential (server-side) clients.

Don't bulk admin-confirm-sign-up UNCONFIRMED users: When users are stuck UNCONFIRMED, prefer resend-confirmation-code so each user re-verifies via confirm-sign-up and proves email ownership (the code likely expired or went to spam). admin-confirm-sign-up flips the status instantly but confirms the account without verifying the email — the attribute stays unverified, which is dangerous when email drives password reset or account linking. Reserve it for trusted/migrated accounts. See troubleshooting.md.

Quick Navigation

Common Workflows

"Add sign-up and login to my React app" → Create a user pool + a public app client (no secret), enable the hosted UI / managed login with the authorization code grant with PKCE, wire the Amplify client library. See user-pools.md and managed-login-oauth.md.

"Add Google / social login" → Register the social IdP on the user pool, map attributes, add the provider to the app client and hosted UI. See managed-login-oauth.md.

"Only authenticated users should call my API" → HTTP API → JWT authorizer; REST API → Cognito user pools authorizer. See api-authorization.md.

"Let the browser upload to S3 after login" → User pool for sign-in, then an identity pool to vend scoped temporary credentials. See identity-pools.md.

Troubleshooting

Full tables in troubleshooting.md.

Security Considerations

• Public clients (SPA/mobile): no client secret, authorization code grant with PKCE, request least-privilege scopes.
• Enable MFA (TOTP or SMS), a strong password policy, and advanced security / threat protection where available.
• Short access-token lifetime; enable refresh token rotation and token revocation; prefer cookieStorage over localStorage.
• Identity pools: scope the authenticated IAM role tightly; disable unauthenticated (guest) access unless required.
• Validate JWTs against the user pool JWKS (iss, aud/client_id, token_use, exp) on every protected request. Use a maintained library such as aws-jwt-verify rather than hand-rolling verification.
• Set security headers on the app's web pages: Content-Security-Policy (restrict script sources to mitigate token-stealing XSS), Strict-Transport-Security (HSTS), X-Frame-Options/frame-ancestors (clickjacking on login pages), and X-Content-Type-Options: nosniff.
• Enable logging and monitoring: CloudTrail for Cognito API events (sign-up/sign-in/admin), user pool threat protection (adaptive auth + event logging), CloudWatch alarms on failed/throttled auth, and API Gateway access logging for authorizer decisions.
• All Cognito and API endpoints are HTTPS/TLS only; enable encryption at rest with a customer-managed KMS key (and restricted key access) on CloudWatch Log groups, SNS topics used for MFA/notifications, and any identity-pool-fronted upload buckets.
• If using SNS for MFA/notification delivery, enable server-side encryption (KMS) on the topic, and keep SMS/email message content limited to what the recipient needs — don't include more PII than the message requires.
• References: Amazon Cognito security features (user pools), Amazon Cognito security (top-level, incl. identity pools), and IAM/STS best practices.

Where to Look When This Skill Is Silent

When you need depth beyond this skill — exact parameter shapes, current limits, edge behaviors — fall back to the authoritative AWS sources rather than guessing. Pointers age much slower than content, so this map stays useful without the skill having to grow.

• API reference (exact params, defaults, errors): Cognito User Pools API and Cognito Identity API
• Developer Guide (concepts, workflows): Amazon Cognito Developer Guide
• Quotas, rate limits, session-cookie lifetime: Cognito quotas
• Feature plans / tier gating: Cognito feature plans
• Pricing: Amazon Cognito pricing
• CLI reference: aws cognito-idp and aws cognito-identity

Not Covered By This Skill

• Amplify Gen2 backend (defineAuth, amplify/auth.ts, npx ampx sandbox).
• IAM policy/role/trust-policy authoring, STS, IAM Identity Center console SSO.
• API Gateway route/integration setup and Lambda function implementation (this skill covers only the Cognito/JWT authorizer configuration and the purpose of Cognito Lambda triggers).