Skip to content

opensite-ai/opensite-skills / aws-auth

aws-auth

Verified

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

references/troubleshooting.md

View on GitHub
# Auth Troubleshooting

## Overview

The most common Cognito failures, by symptom, with root cause and fix.

## Redirect & hosted UI

| Symptom | Cause | Fix |
|---------|-------|-----|
| `redirect_mismatch` after login | Callback URL not registered exactly (scheme/host/path/trailing slash/case) | Add the exact callback URL to the app client's Allowed callback URLs; localhost must be `http://localhost:<port>`, all else HTTPS |
| Login page 400 "invalid_request" | Missing/invalid `response_type`, `client_id`, or unsupported scope | Send `response_type=code`, a valid client id, and scopes the client allows |
| `invalid_grant` at `/oauth2/token` | Code reused, expired, or `code_verifier` missing/wrong | Exchange the code once, promptly, with the matching PKCE verifier |
| CORS error hitting hosted UI or token endpoint | Browser calling `/oauth2/token` cross-origin, or proxying it | Do the code+PKCE exchange client-side per the flow; don't proxy the token endpoint |

## Client secret / auth flow

| Symptom | Cause | Fix |
|---------|-------|-----|
| `NotAuthorizedException: Unable to verify secret hash` | Client secret set on a public (SPA/mobile) client | Recreate the app client with no secret, or compute `SECRET_HASH` in a server-side client |
| `InvalidParameterException: Auth flow not enabled` | The flow isn't in the client's explicit auth flows | Add e.g. `ALLOW_USER_SRP_AUTH` / `ALLOW_REFRESH_TOKEN_AUTH` (note: `ALLOW_REFRESH_TOKEN_AUTH` is incompatible with refresh-token rotation — with rotation on, use `GetTokensFromRefreshToken` instead) |
| Password auth rejected | `ALLOW_USER_PASSWORD_AUTH` disabled (good default) | Use SRP; enable password auth only for migration/server flows |

## Tokens & sessions

| Symptom | Cause | Fix |
|---------|-------|-----|
| Forced re-login every hour | Not using the refresh token | Refresh via `GetTokensFromRefreshToken` / Amplify auto-refresh |
| `Refresh Token has been revoked` | Rotation invalidated the old refresh token | Always use the newest refresh token returned by each refresh |
| API returns 401 with a "valid" token | Issuer/audience mismatch or wrong token type | Issuer `https://cognito-idp.<region>.amazonaws.com/<pool-id>`, audience = client id; send the expected token (see api-authorization.md) |

## MFA & sign-up

| Symptom | Cause | Fix |
|---------|-------|-----|
| TOTP enrollment fails | Software MFA not enabled on the pool | `set-user-pool-mfa-config --software-token-mfa-configuration Enabled=true` |
| Users stuck `UNCONFIRMED` | Verification code expired, never entered, or went to spam | Prefer `resend-confirmation-code` so each user re-verifies via `confirm-sign-up` — this proves email ownership. `admin-confirm-sign-up` flips the status instantly but confirms the account **without verifying the email**, leaving the attribute unverified (risky when email drives password reset / account linking); reserve it for trusted or migrated accounts and set the attribute verified separately only when ownership is established another way. |
| Sign-up blocked unexpectedly | Pre sign-up trigger returned an error | Inspect the trigger's logic/logs; it halts the sign-up on error |

## Federation

| Symptom | Cause | Fix |
|---------|-------|-----|
| Social user "already exists" / duplicate accounts | Same email across IdPs creates separate users | Enable attribute mapping and deliberate account linking; treat email as non-unique across providers |
| Missing name/email after social login | IdP claims not mapped to pool attributes | Set `--attribute-mapping` on the identity provider |
| SAML login fails | Metadata stale or attribute mapping wrong | Refresh IdP metadata; verify NameID/attribute mapping |

## Identity pools

| Symptom | Cause | Fix |
|---------|-------|-----|
| `Token is not from a supported provider` | Provider/ClientId not registered on the identity pool | Match `cognito-idp.<region>.amazonaws.com/<pool-id>` and the app client id |
| `Access denied` after credentials returned | Authenticated role policy too narrow / trust policy wrong | Fix the role (see `aws-iam`); ensure it trusts `cognito-identity.amazonaws.com` for the pool |

## Related

- [managed-login-oauth.md](managed-login-oauth.md), [tokens-and-sessions.md](tokens-and-sessions.md),
  [api-authorization.md](api-authorization.md), [identity-pools.md](identity-pools.md).

## Authoritative sources

- [Amazon Cognito user pools — Developer Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html)
- [Managed login & federation error responses (redirect/token errors)](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html)
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall