/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.

| You need... | Use | Why | |-------------|-----|-----| | Sign-up / sign-in, user directory, issue JWTs | **User pool** | It authenticates users and is an OIDC IdP | | The signed-in client to call S3/DynamoDB/etc. directly with AWS credentials | **Identity pool** | It exchanges a token for temporary AWS credentials via STS | | Both (sign in, then hit AWS resources from the browser/app) | User pool → identity pool | Identity pool trusts the user pool as its IdP |

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](references/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](references/managed-login-oauth.md) and [identity-pools.md](references/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](references/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](references/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](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-sign-in-feature-plans.html) 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](references/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](references/troubleshooting.md).

Quick Navigation

| You want to... | Go to | |----------------|-------| | Create a user pool, s