[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7A61XFXFV9BA2FSG6AARF79":3,"skill-same:01M7A61XFXFV9BA2FSG6AARF79":148},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":45,"commitSha":46,"skillDirectory":47,"forksCount":48,"repositoryHtmlUrl":49,"repositoryHomepageUrl":6,"ownerHtmlUrl":50,"ownerBlogUrl":6,"ownerDescription":51,"updatedAt":52,"install":53,"resources":66},"01M7A61XFXFV9BA2FSG6AARF79","cognito-auth-troubleshooter",null,"Diagnoses Amazon Cognito authentication failures through a twelve-category diagnostic tree: User Pool sign-in errors (wrong app client, wrong auth flow, client secret mismatch on PUBLIC clients), token refresh failures (refresh token expired, token revocation, JWKS mismatch), hosted UI redirect mismatch (callback URL must match exactly), custom attribute write permissions (writable vs readable attributes), pre-token-generation Lambda trigger errors, identity pool (federated identities) role assumption failures (unauthenticated role trust policy must allow cognito-identity), social provider (Google\u002FFacebook\u002FApple) misconfiguration, SAML provider certificate mismatch, MFA setup and bypass issues, password policy violations, account recovery flow errors, custom sender Lambda trigger errors, domain prefix conflicts, and TLS certificate issues. Walks symptoms to a verified root cause with evidence-backed probes; emits ROOT_CAUSE_IDENTIFIED or INSUFFICIENT_DATA.","jhkchan\u002Faws-agent-skills","jhkchan","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1083902?v=4","01M7A2SVQYP9GQTPTDXP5JKYQ4","Jacky Chan","01M7A2SVS117YWCTZABB75HZR1",4,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: cognito-auth-troubleshooter\ndescription: 'Diagnoses Amazon Cognito authentication failures through a twelve-category diagnostic tree: User Pool sign-in errors (wrong app client, wrong auth flow, client secret mismatch on PUBLIC clients), token refresh failures (refresh token expired, token revocation, JWKS mismatch), hosted UI redirect mismatch (callback URL must match exactly), custom attribute write permissions (writable vs readable attributes), pre-token-generation Lambda trigger errors, identity pool (federated identities) role assumption failures (unauthenticated role trust policy must allow cognito-identity), social provider (Google\u002FFacebook\u002FApple) misconfiguration, SAML provider certificate mismatch, MFA setup and bypass issues, password policy violations, account recovery flow errors, custom sender Lambda trigger errors, domain prefix conflicts, and TLS certificate issues. Walks symptoms to a verified root cause with evidence-backed probes; emits ROOT_CAUSE_IDENTIFIED or INSUFFICIENT_DATA.'\nlicense: Apache-2.0\ncompatibility: Agent runtime that reads SKILL.md (Claude Code, Cursor, Windsurf, Codex, Gemini). Offline symptom classification works from pasted error messages and user-pool configuration. Live-account diagnosis uses aws cognito-idp describe-user-pool, describe-user-pool-client, describe-identity-pool, get-identity-pool-roles, list-user-pools, list-user-pool-clients, aws lambda get-function \u002F get-policy (for triggers), aws iam simulate-principal-policy, aws cloudtrail lookup-events, aws logs...\nmetadata:\n  domain: aws-cloudops\n  complexity: high\n  requires_llm: 'true'\n  phase: '2'\n  supports_pipeline: 'true'\n  entry_point: 'false'\n  family: Security\n  task_type: troubleshoot\n  skill_class: capability\n  lifecycle_status: active\n  verdict_shape: ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA\n  when_to_use: Diagnosing a Cognito authentication failure (sign-in error, token refresh failure, hosted UI redirect mismatch, social or SAML provider error, MFA setup or bypass, identity pool role assumption failure, pre-token-generation Lambda error, domain prefix conflict, TLS error), walking a symptom to the failed layer with verify and fix commands, validating why a user cannot authenticate, or triaging a \"users cannot log in\" page where the root cause may be app client config, auth flow, token lifecycle, hosted UI, provider, trigger Lambda, or identity pool role trust — not necessarily the application code.\n  when_not_to_use: Application-level session management beyond Cognito token exchange (use the application framework's auth docs), API Gateway custom authorizer debugging (use apigateway-http-troubleshooter), root-cause analysis of the user's device or browser (use browser developer tools and device logs), or IAM policy authoring for the authenticated\u002Funauthenticated roles (use iam-least-privilege-advisor). This skill diagnoses Cognito authentication-time failures; it does not audit steady-state security posture or tune application session logic.\n  activation_triggers: Cognito authentication failed, Cognito NotAuthorizedException, Cognito UserLambdaValidationException, Cognito InvalidParameterException, Cognito redirect mismatch, Cognito hosted UI callback URL, Cognito token refresh failed, Cognito refresh token expired, Cognito InvalidGrantException, Cognito pre-token-generation Lambda error, Cognito identity pool role assumption, Cognito unauthenticated role, cognito-identity amazonaws com, Cognito social provider Google, Cognito Facebook login, Cognito SignInWithApple, Cognito SAML provider, Cognito SAML certificate, Cognito MFA setup failed, Cognito MFA bypass, Cognito password policy, Cognito custom attributes, Cognito domain prefix, Cognito TLS certificate, troubleshoot Cognito authentication\n  invocation_schema: 'Input: either (a) a symptom description (error message, observed behaviour, \"users cannot log in\", \"token refresh returns InvalidGrantException\"), optionally paired with the User Pool \u002F Identity Pool configuration and recent CloudWatch logs, OR (b) a UserPoolId \u002F IdentityPoolId plus client context (AppClientId, auth flow, provider name, observed error) for live-account diagnosis. Output: a deterministic TARGET\u002FVERDICT\u002FREASON\u002FLAYER\u002FEVIDENCE\u002FREMEDIATION block where VERDICT ∈ {ROOT_CAUSE_IDENTIFIED, INSUFFICIENT_DATA} and LAYER ∈ {APP_CLIENT_CONFIG, APP_CLIENT_SECRET, AUTH_FLOW, TOKEN_REFRESH, TOKEN_REVOCATION, HOSTED_UI_REDIRECT, CUSTOM_ATTRIBUTE, PRE_TOKEN_GEN_LAMBDA, IDENTITY_POOL_ROLE, IDENTITY_POOL_TRUST, SOCIAL_PROVIDER, SOCIAL_REDIRECT, SAML_PROVIDER, SAML_CERTIFICATE, MFA_CONFIG, MFA_TOTP, MFA_SMS, PASSWORD_POLICY, ACCOUNT_RECOVERY, CUSTOM_SENDER_LAMBDA, DOMAIN_PREFIX, TLS_CERTIFICATE, UNKNOWN}.'\n  invocation_example: '# Minimal valid input (offline symptom classification):\n\n    Symptom: \"Users report ''redirect_mismatch'' error after entering credentials\n\n    on the Cognito hosted UI. The callback URL in the browser bar shows\n\n    https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback but the app client is configured\n\n    with https:\u002F\u002Fapp.example.com\u002Fcallback.\"\n\n    UserPoolId: us-east-1_AbCdEf123\n\n    AppClientId: 1ab2cd3ef4gh5ij6lmn7opq8rs\n\n    AuthFlow: code grant (hosted UI)\n\n    Domain: auth.example.com (Cognito domain prefix)\n\n    HostedUI callback URLs: https:\u002F\u002Fapp.example.com\u002Fcallback\n\n    Expected callback (from app config): https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback'\n  version: 0.1.0\n  author: Jacky Chan — AWS Community Builder\n  keywords: Cognito, User Pool, Identity Pool, authentication, authorization, token refresh, access token, ID token, refresh token, JWT, JWKS, hosted UI, callback URL, redirect URI, app client, client secret, PUBLIC client, CONFIDENTIAL client, auth flow, ALLOW_USER_PASSWORD_AUTH, ALLOW_USER_SRP_AUTH, ALLOW_REFRESH_TOKEN_AUTH, custom attributes, pre-token-generation, Lambda trigger, identity pool, federated identities, unauthenticated role, trust policy, cognito-identity, social provider, Google, Facebook, SignInWithApple, SAML, certificate mismatch, MFA, TOTP, SMS MFA, password policy, account recovery, custom sender, domain prefix, TLS certificate, troubleshooting\n  tags: cognito, security, troubleshooting, authentication, user-pool, identity-pool, hosted-ui, jwt, saml, mfa\n---\n\n# Cognito Auth Troubleshooter\n\n## Quick start\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Mindset\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Philosophy\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Expert heuristic\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Quick reference — symptom triage table\n\n| Symptom phrase \u002F error | Most likely layer | First probe |\n|---|---|---|\n| `NotAuthorizedException`, `error: invalid_client` | APP_CLIENT_SECRET | `describe-user-pool-client` (ClientSecret present? Client sending secret?) |\n| `NotAuthorizedException`, `error: invalid_grant` | TOKEN_REFRESH \u002F AUTH_FLOW | `describe-user-pool-client` (ExplicitAuthFlows), check token expiry |\n| `redirect_mismatch`, `invalid_redirect_uri` | HOSTED_UI_REDIRECT | `describe-user-pool-client` (CallbackURLs) vs app config |\n| `UserLambdaValidationException` | PRE_TOKEN_GEN_LAMBDA \u002F CUSTOM_SENDER_LAMBDA | CloudWatch Logs for the trigger Lambda |\n| `GetCredentialsForIdentity` -> `NotAuthorizedException` | IDENTITY_POOL_ROLE \u002F IDENTITY_POOL_TRUST | `get-identity-pool-roles` + IAM role trust policy |\n| Social login button -> blank page or error | SOCIAL_PROVIDER \u002F SOCIAL_REDIRECT | User Pool domain + app client callback + provider redirect URIs |\n| SAML login -> `InvalidSAMLRole` or loop | SAML_PROVIDER \u002F SAML_CERTIFICATE | Provider metadata, certificate fingerprint |\n| MFA code rejected | MFA_CONFIG \u002F MFA_TOTP \u002F MFA_SMS | User Pool MFA config, user's MFA settings |\n| Password rejected on signup\u002Freset | PASSWORD_POLICY | User Pool Policies (password policy) |\n| Custom attribute write -> `ResourceNotFoundException` or silent failure | CUSTOM_ATTRIBUTE | `describe-user-pool` (SchemaAttributes, `Mutable` flag) |\n| Domain prefix -> `DomainAlreadyExists` | DOMAIN_PREFIX | `describe-user-pool-domain` \u002F `list-user-pool-domains` |\n| TLS error on auth domain | TLS_CERTIFICATE | Certificate status, ACM, CloudFront distribution |\n\n## Pre-flight: pool state and gather-info gate\n\nBefore running symptom-specific probes, gather the canonical pool\nconfiguration and short-circuit on pool states that mimic authentication\nfailures. Misclassifying these produces hours of debugging for a problem\nthat is not an auth problem.\n\n### Account-wide pre-flight commands\n\nMoved verbatim to [references\u002Fcognito-troubleshooting-commands.md](references\u002Fcognito-troubleshooting-commands.md) - load on demand (see References below).\n\n### Pool-state short-circuit\n\n| Configuration field | Effect on diagnosis |\n|---|---|\n| `UserPool.MfaConfiguration: OFF` but user has `SMS_MFA` or `SOFTWARE_AUTH_MFA` setting | MFA was enabled per-user but pool-level MFA is OFF. The user's MFA setting is stale; clear it via `admin-set-user-mfa-preference`. |\n| `UserPool.LambdaConfig.PreTokenGeneration` points at a Lambda that does not exist | Every sign-in fails with `UserLambdaValidationException`. Verify the Lambda ARN resolves. |\n| `UserPool.Domain` empty but hosted UI is used | The hosted UI requires a domain prefix or custom domain. Without it, the auth domain returns 404. |\n| `UserPoolClient.ClientSecret` empty but client sends `client_secret` | PUBLIC client sending a secret that does not exist. The SDK returns `Unauthorized`. |\n| `UserPoolClient.ClientSecret` present but client omits it | CONFIDENTIAL client omitting the secret. The SDK returns `invalid_client`. |\n\n### Alias \u002F app client pre-flight\n\n| Field | Effect |\n|---|---|\n| `UserPoolClient.ExplicitAuthFlows` does not include `ALLOW_USER_PASSWORD_AUTH` | Direct `AdminInitiateAuth` with `USER_PASSWORD_AUTH` flow fails. Add the flow to the allow list. |\n| `UserPoolClient.AllowedOAuthFlows` empty | OAuth\u002FOIDC flows (code grant, implicit) via hosted UI fail. Configure `[\"code\", \"implicit\"]`. |\n| Multiple app clients, caller uses the wrong one | Each app client has its own callback URLs, flows, and scopes. Verify the caller's `client_id` matches the intended app client. |\n| `UserPoolClient.PreventUserExistenceErrors: true` | Cognito returns generic `NotAuthorizedException` instead of `UserNotFoundException`. This is a security feature, not a bug. |\n\nIf the input is malformed (missing UserPoolId or AppClientId, absent\nsymptom description, no error string for offline diagnosis), emit:\n\n```text\nTARGET: \u003Cpool-id \u002F client-id or unknown>\nVERDICT: INSUFFICIENT_DATA\nREASON: Input is missing required context — at minimum a symptom\n  description (the error string or observed behaviour) and the\n  UserPoolId or AppClientId.\nLAYER: UNKNOWN\nEVIDENCE:\n  - Missing: \u003Clist specific missing fields>\nREMEDIATION: Re-prompt the operator for: (1) the exact error string or\n  observed symptom, (2) the UserPoolId and AppClientId, (3) the auth\n  flow being used (hosted UI code grant, implicit, USER_PASSWORD_AUTH,\n  USER_SRP_AUTH, etc.), and (4) for identity pool issues, the\n  IdentityPoolId and whether the user is authenticated or\n  unauthenticated.\n```\n\n## Process — Diagnostic decision tree (apply in symptom order)\n\nThe diagnostic tree is symptom-driven. Pick the entry point based on the\nobserved symptom, then walk the layer-specific probes in order. Each layer\nends with either a positive root-cause confirmation (failing probe that\nmatches the symptom) or a pass that moves to the next layer. **Never emit\nROOT_CAUSE_IDENTIFIED without a failing probe that matches the symptom.**\n\n### Step 0: Non-obvious behaviours that change diagnosis\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 1: Symptom entry — pick the diagnostic branch\n\nMap the symptom to a branch and jump to that branch's section. If the\nsymptom matches none of the categories, route to Step 13 (INSUFFICIENT_DATA).\n\n| Symptom | Branch |\n|---|---|\n| `NotAuthorizedException` on sign-in, `invalid_client` | Step 2 — App client |\n| `NotAuthorizedException` on sign-in, `invalid_grant` \u002F wrong flow | Step 3 — Auth flow |\n| `redirect_mismatch` \u002F `invalid_redirect_uri` | Step 4 — Hosted UI redirect |\n| `InvalidGrantException` on refresh token exchange | Step 5 — Token refresh |\n| `UserLambdaValidationException` on sign-in | Step 6 — Lambda triggers |\n| `GetCredentialsForIdentity` -> `NotAuthorizedException` | Step 7 — Identity pool |\n| Social login button -> error \u002F blank page | Step 8 — Social provider |\n| SAML login -> `SAMLResponseDoesNotMatch` \u002F loop | Step 9 — SAML provider |\n| MFA code rejected \u002F cannot set up MFA | Step 10 — MFA |\n| Password rejected on signup or reset | Step 11 — Password policy |\n| Custom attribute write fails | Step 12 — Custom attribute |\n| `DomainAlreadyExistsException` | Step 12b — Domain prefix |\n| TLS error on auth domain | Step 12c — TLS certificate |\n| None of the above | Step 13 — INSUFFICIENT_DATA |\n\n### Step 2: App client secret — CONFIDENTIAL vs PUBLIC\n\nSymptom: `NotAuthorizedException` with `error: invalid_client` or a\ngeneric \"authentication failed\" on the very first API call. The error\nfires before any user credentials are validated, because the client\nitself is not authenticated.\n\n```bash\naws cognito-idp describe-user-pool-client \\\n  --user-pool-id \u003Cpool-id> --client-id \u003Cclient-id> --output json | \\\n  jq '{ClientId, ClientSecret: (.ClientSecret != null), ExplicitAuthFlows, AllowedOAuthFlows}'\n```\n\nKey checks:\n\n| Condition | Diagnosis |\n|---|---|\n| `ClientSecret` present (non-null) but client does not send it | CONFIDENTIAL client used as PUBLIC. Fix: include the secret in the token exchange, or recreate the client with `GenerateClientSecret: false`. |\n| `ClientSecret` absent (null) but client sends a fabricated secret | PUBLIC client sent a secret. Fix: remove the `client_secret` parameter from the SDK call. |\n| `ClientSecret` present and client sends it, but value is wrong | Stale secret (rotated or recreated). Fix: retrieve the current secret via `describe-user-pool-client` and update the application config. |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: APP_CLIENT_SECRET`. Fix:\neither align the client type with the usage (PUBLIC or CONFIDENTIAL)\nor ensure the correct secret value is used.\n\n### Step 3: Auth flow — wrong or missing flow\n\nMoved verbatim to [references\u002Fcognito-auth-flow-reference.md](references\u002Fcognito-auth-flow-reference.md) - load on demand (see References below).\n\n### Step 4: Hosted UI redirect mismatch\n\nSymptom: `redirect_mismatch` or `invalid_redirect_uri` from the hosted\nUI `\u002Foauth2\u002Fauthorize` endpoint. The browser URL shows the Cognito\nauth domain with an error parameter.\n\n```bash\naws cognito-idp describe-user-pool-client \\\n  --user-pool-id \u003Cpool-id> --client-id \u003Cclient-id> --output json | \\\n  jq '.CallbackURLs'\n```\n\nCross-reference each `CallbackURL` against the `redirect_uri` parameter\nthe application sends:\n\n| Mismatch type | Example | Fix |\n|---|---|---|\n| Trailing slash | App: `https:\u002F\u002Fapp.example.com\u002Fcallback\u002F` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | Add the trailing-slash variant to `CallbackURLs` (or remove it from the app) |\n| Scheme | App: `http:\u002F\u002Fapp.example.com\u002Fcallback` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | Match the scheme (prefer HTTPS) |\n| Port | App: `https:\u002F\u002Fapp.example.com:8443\u002Fcallback` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | Add the port to `CallbackURLs` |\n| Path | App: `https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | Add the exact path |\n| Case | App: `https:\u002F\u002FApp.Example.Com\u002Fcallback` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | DNS is case-insensitive but Cognito compares case-sensitively; normalise |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: HOSTED_UI_REDIRECT`. Fix:\nupdate the app client `CallbackURLs` to include the exact redirect URI\nthe application sends.\n\n### Step 5: Token refresh failure\n\nMoved verbatim to [references\u002Fcognito-auth-flow-reference.md](references\u002Fcognito-auth-flow-reference.md) - load on demand (see References below).\n\n### Step 6: Lambda trigger errors\n\nSymptom: `UserLambdaValidationException` on sign-in, sign-up, forgot\npassword, or any auth flow. The error message typically contains the\nLambda's exception type and message.\n\n```bash\naws cognito-idp describe-user-pool \\\n  --user-pool-id \u003Cpool-id> --output json | \\\n  jq '.UserPool.LambdaConfig'\n\naws logs filter-log-events \\\n  --log-group-name \u002Faws\u002Flambda\u002F\u003Ctrigger-name> \\\n  --start-time $(date -d '-30 minutes' +%s)000 \\\n  --filter-pattern '\"ERROR\" OR \"Exception\" OR \"Task timed out\"' \\\n  --output json\n```\n\nCommon trigger failure patterns:\n\n| Trigger | Error | Common cause |\n|---|---|---|\n| `PreTokenGeneration` | `UserLambdaValidationException` on every sign-in | Lambda throws on malformed event, response exceeds 100 KB, or response shape does not match `{claimsToAddOrOverride, claimsToSuppress}` |\n| `PreSignUp` | `UserLambdaValidationException` on sign-up | Lambda does not return `event.response.autoConfirmUser` or returns wrong shape |\n| `PostConfirmation` | `UserLambdaValidationException` after confirmation | Lambda times out calling downstream (e.g., DynamoDB, SES) |\n| `CustomMessage` | `UserLambdaValidationException` on verification email | Lambda returns empty `event.response.emailMessage` or missing `emailSubject` |\n| `DefineAuthChallenge` \u002F `CreateAuthChallenge` \u002F `VerifyAuthChallenge` | Custom auth flow fails | State machine logic error in the trigger sequence |\n| `CustomSMSSender` \u002F `CustomEmailSender` | `InvalidParameterException` | KMS key missing or Lambda cannot decrypt; Lambda does not return the expected `response.smsMessage` \u002F `response.emailMessage` |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: PRE_TOKEN_GEN_LAMBDA` (or\nthe trigger-specific layer). Fix: address the Lambda error (code fix,\ntimeout increase, IAM permission for downstream calls).\n\n### Step 7: Identity pool role assumption failure\n\nSymptom: `GetCredentialsForIdentity` returns `NotAuthorizedException`\nor `AccessDenied`. The User Pool login succeeded (JWT issued) but the\nIdentity Pool cannot exchange the token for AWS credentials.\n\n```bash\naws cognito-identity get-identity-pool-roles \\\n  --identity-pool-id \u003Cidentity-pool-id> --output json\n\n# Check the role trust policy\nROLE_NAME=$(echo \u003Crole-arn> | cut -d\u002F -f2)\naws iam get-role --role-name \u003Crole-name> --output json | \\\n  jq '.Role.AssumeRolePolicyDocument'\n```\n\nKey checks for the trust policy:\n\n| Condition | Expected value |\n|---|---|\n| `Principal` | `\"cognito-identity.amazonaws.com\"` |\n| `Action` | `\"sts:AssumeRoleWithWebIdentity\"` (or `\"sts:AssumeRoleWithWebIdentity\"` in newer policies) |\n| `Condition.StringEquals[\"cognito-identity.amazonaws.com:aud\"]` | Must match the Identity Pool ID |\n| `Condition.StringEquals[\"cognito-identity.amazonaws.com:amr\"]` (unauth role) | Must contain `\"unauth\"` |\n| `Condition.StringEquals[\"cognito-identity.amazonaws.com:amr\"]` (auth role) | Must contain `\"authenticated\"` or a provider-specific value |\n\nCommon failure patterns:\n\n| Pattern | Cause |\n|---|---|\n| `aud` condition references a different (old) identity pool ID | Trust policy not updated after pool recreation. Fix: update the condition. |\n| `amr` condition missing for unauthenticated role | Unauthenticated access denied. Fix: add `\"unauth\"` to the `amr` condition. |\n| Role does not exist or was deleted | `get-identity-pool-roles` shows a role ARN that IAM cannot find. Fix: recreate the role with the correct trust policy. |\n| RoleMapping type is `Token` but provider is not configured | The identity pool does not have the User Pool as a configured provider. Fix: add the Cognito User Pool as an identity provider. |\n| `RoleMappings` has no rules and `Roles` is empty | No roles configured at all. Fix: set both `Roles` (auth + unauth) and `RoleMappings`. |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: IDENTITY_POOL_TRUST` (trust\npolicy) or `IDENTITY_POOL_ROLE` (role missing or misconfigured).\n\n### Step 8: Social provider misconfiguration\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 9: SAML provider certificate mismatch\n\nSymptom: SAML login returns `SAMLResponseDoesNotMatch`,\n`InvalidSAMLRole`, or the login loops between the IdP and Cognito.\n\n```bash\naws cognito-idp describe-identity-provider \\\n  --user-pool-id \u003Cpool-id> --provider-name \u003Csaml-provider-name> --output json | \\\n  jq '.ProviderDetails'\n\n# If using metadata URL, verify it is reachable:\ncurl -sI \u003Cmetadata-url> | head -5\n```\n\nKey checks:\n\n| Check | Expected |\n|---|---|\n| `ProviderType` | `SAML` |\n| `ProviderDetails.MetadataURL` or `MetadataFile` | URL must be reachable and return valid XML; file must be base64-encoded XML |\n| Certificate in metadata | Must match the IdP's current signing certificate; expired or rotated certificates cause `SAMLResponseDoesNotMatch` |\n| `attribute_mapping` | Maps SAML attributes (e.g., `email`) to User Pool attributes |\n| IdP-side Audience \u002F Entity ID | Must be the Cognito User Pool domain (e.g., `https:\u002F\u002F\u003Cdomain>.auth.\u003Cregion>.amazoncognito.com\u002Fsaml2\u002Fidpresponse`) |\n| IdP-side NameID format | Cognito expects `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` by default |\n\nCommon failure patterns:\n\n| Pattern | Cause |\n|---|---|\n| `SAMLResponseDoesNotMatch` | Certificate in metadata does not match the signing certificate used by the IdP. Fix: re-import updated metadata. |\n| Login loop (IdP -> Cognito -> IdP) | The `RelayState` or `InResponseTo` does not match, or Cognito cannot find the user based on the NameID. Fix: check the NameID format and user lookup attribute. |\n| `InvalidSAMLRole` | SAML response references a role ARN that does not exist or is not in the IdP's role mapping. Fix: update the role mapping. |\n| Metadata URL unreachable from Cognito | Cognito fetches the metadata at login time. If the URL is internal or rate-limited, logins fail intermittently. Fix: use `MetadataFile` instead of `MetadataURL`. |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: SAML_CERTIFICATE` (cert\nmismatch) or `SAML_PROVIDER` (metadata \u002F mapping issue).\n\n### Step 10: MFA issues\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 11: Password policy violations\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 12: Custom attribute write permissions\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 12b: Domain prefix conflict\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 12c: TLS certificate issues\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 13: INSUFFICIENT_DATA\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Output format\n\n```text\nTARGET: \u003Cpool-id \u002F client-id \u002F provider name>\nVERDICT: ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA\nREASON: \u003C1-2 sentences naming the failed layer and the failing probe>\nLAYER: \u003CAPP_CLIENT_CONFIG | APP_CLIENT_SECRET | AUTH_FLOW |\n        TOKEN_REFRESH | TOKEN_REVOCATION | HOSTED_UI_REDIRECT |\n        CUSTOM_ATTRIBUTE | PRE_TOKEN_GEN_LAMBDA |\n        IDENTITY_POOL_ROLE | IDENTITY_POOL_TRUST |\n        SOCIAL_PROVIDER | SOCIAL_REDIRECT |\n        SAML_PROVIDER | SAML_CERTIFICATE |\n        MFA_CONFIG | MFA_TOTP | MFA_SMS |\n        PASSWORD_POLICY | ACCOUNT_RECOVERY |\n        CUSTOM_SENDER_LAMBDA | DOMAIN_PREFIX |\n        TLS_CERTIFICATE | UNKNOWN>\nEVIDENCE:\n  - \u003Cobserved symptom — error string or behaviour>\n  - \u003Cfailing probe — command and its output that confirms the cause>\n  - \u003Cpassing probes — layers ruled out>\nREMEDIATION:\n  1. \u003Cspecific action with CLI command>\n  2. \u003Cverification command after the fix>\nCONFIRM: Before executing any state-changing CLI, emit and await operator\n  approval: \"CONFIRM: About to \u003Caction> on \u003Cpool \u002F client> in \u003Cregion>.\n  Proceed? (yes\u002Fno)\"\n```\n\n### Worked example — Hosted UI redirect mismatch\n\n```text\nTARGET: us-east-1_AbCdEf123 \u002F client 1ab2cd3ef4gh5ij6lmn7opq8rs\nVERDICT: ROOT_CAUSE_IDENTIFIED\nREASON: The application sends redirect_uri=https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback\n  but the app client CallbackURLs lists only\n  https:\u002F\u002Fapp.example.com\u002Fcallback. The path \u002Fauth\u002Fcallback is missing\n  from the configured callback list (Step 4).\nLAYER: HOSTED_UI_REDIRECT\nEVIDENCE:\n  - Symptom: all users see redirect_mismatch error after entering\n    credentials on the hosted UI. The browser address bar shows\n    redirect_uri=https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback.\n  - Probe: aws cognito-idp describe-user-pool-client returns\n    CallbackURLs: [\"https:\u002F\u002Fapp.example.com\u002Fcallback\"] — the path\n    \u002Fauth\u002Fcallback is absent.\n  - Passing: ClientSecret is null (PUBLIC client, no secret mismatch);\n    ExplicitAuthFlows includes ALLOW_REFRESH_TOKEN_AUTH and\n    ALLOW_USER_SRP_AUTH; no Lambda triggers configured.\nREMEDIATION:\n  1. Add the correct callback URL to the app client:\n     aws cognito-idp update-user-pool-client \\\n       --user-pool-id us-east-1_AbCdEf123 \\\n       --client-id 1ab2cd3ef4gh5ij6lmn7opq8rs \\\n       --callback-urls \"https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback\" \"https:\u002F\u002Fapp.example.com\u002Fcallback\"\n  2. Verify by navigating to the hosted UI authorize endpoint with\n     redirect_uri=https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback — the redirect\n     should succeed without error.\nCONFIRM: Before updating the app client, emit and await:\n  \"CONFIRM: About to add https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback to\n   CallbackURLs on client 1ab2cd3ef4gh5ij6lmn7opq8rs. Proceed? (yes\u002Fno)\"\n```\n\n### Worked example — Identity pool unauthenticated role trust policy\n\nMoved verbatim to [references\u002Fworked-examples.md](references\u002Fworked-examples.md) - load on demand (see References below).\n\n### Worked example — Pre-token-generation Lambda error\n\nMoved verbatim to [references\u002Fworked-examples.md](references\u002Fworked-examples.md) - load on demand (see References below).\n\n## Anti-Patterns — NEVER\n\n- NEVER declare ROOT_CAUSE_IDENTIFIED without a failing probe that\n  matches the symptom. A \"process of elimination\" diagnosis erodes\n  operator trust when the real cause is elsewhere.\n\n- NEVER assume the app client is PUBLIC because the application is a\n  SPA. Check `describe-user-pool-client` for `ClientSecret` presence.\n  Many SPAs use CONFIDENTIAL clients with a server-side proxy for the\n  secret; others are truly PUBLIC. The diagnostic is driven by config,\n  not by application type.\n\n- NEVER add a `client_secret` to a PUBLIC client call. The secret does\n  not exist; sending a fabricated value produces `Unauthorized`. If the\n  client was created without a secret, the SDK must not send one.\n\n- NEVER compare the `redirect_uri` loosely. Scheme, host, port, path,\n  and trailing slash must all match exactly. A single character\n  difference (including case) produces `redirect_mismatch`.\n\n- NEVER assume the identity pool role trust policy is correct because\n  \"it worked before.\" Pool IDs change when pools are recreated; the\n  `aud` condition must reference the CURRENT pool ID. Always verify\n  the trust policy's `aud` condition against the live pool ID.\n\n- NEVER forget the `amr` condition for the unauthenticated role. The\n  trust policy must include\n  `\"ForAnyValue:StringLike\": {\"cognito-identity.amazonaws.com:amr\": \"unauth\"}`\n  for unauthenticated access. Omitting it silently breaks guest access.\n\n- NEVER assume the pre-token-generation Lambda is correct because the\n  code \"hasn't changed.\" If the upstream IdP stopped sending a claim\n  that the Lambda reads, the Lambda throws even though the Lambda code\n  is unchanged. Always check CloudWatch Logs for the trigger.\n\n- NEVER update a SAML provider's metadata without verifying the\n  certificate. If the IdP rotated its signing certificate and the new\n  metadata has the correct cert, updating fixes the issue. But if the\n  metadata still has the OLD cert, updating is a no-op and the logins\n  still fail.\n\n- NEVER use `MfaConfiguration: ON` at pool level and then try to\n  disable MFA per-user. Pool-level `ON` enforces MFA for all users.\n  To make MFA optional, use `MfaConfiguration: OPTIONAL`.\n\n- NEVER recreate a User Pool to \"fix\" a config issue without exporting\n  users first. Pool recreation changes the Pool ID, invalidating all\n  existing JWTs, app client IDs, identity pool mappings, and trigger\n  Lambda ARNs. Always attempt to fix the config in place.\n\n- NEVER assume a custom attribute can be updated after sign-up. Check\n  the `Mutable` flag. If `Mutable: false`, the attribute is write-once\n  at sign-up time. Making it mutable requires creating a new pool with\n  the corrected attribute.\n\n- NEVER set `RefreshTokenValidity` without checking\n  `TokenValidityUnits.RefreshToken`. A value of `30` could be 30\n  seconds, 30 minutes, 30 hours, or 30 days depending on the unit.\n  The default unit is `days`.\n\n- NEVER send the `client_secret` in the browser for a PUBLIC client.\n  Even if the client has a secret (misconfigured CONFIDENTIAL client\n  used by a SPA), the secret should be proxied through a backend, not\n  exposed in client-side code.\n\n## Pre-flight safety checks (run before any state-changing CLI)\n\nMoved verbatim to [references\u002Fcognito-troubleshooting-commands.md](references\u002Fcognito-troubleshooting-commands.md) - load on demand (see References below).\n\n## Remediation guidance\n\nMoved verbatim to [references\u002Ferror-handling.md](references\u002Ferror-handling.md) - load on demand (see References below).\n\n## Deep reference: Cognito authentication layer model\n\nMoved verbatim to [references\u002Fcognito-auth-flow-reference.md](references\u002Fcognito-auth-flow-reference.md) - load on demand (see References below).\n\n## Recent AWS features (2024-2026)\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## References (load on demand)\n\n- [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - quick-start detail, mindset\u002Fphilosophy\u002Fexpert heuristics, Step 0 gotchas, extended branches (Steps 8-13), recent AWS features\n- [references\u002Fworked-examples.md](references\u002Fworked-examples.md) - secondary worked examples (identity pool trust, pre-token Lambda)\n- [references\u002Ferror-handling.md](references\u002Ferror-handling.md) - remediation guidance per layer\n- [references\u002Fcognito-auth-flow-reference.md](references\u002Fcognito-auth-flow-reference.md) - auth-flow layer model, token lifecycle, Steps 3\u002F5 detail\n- [references\u002Fcognito-troubleshooting-commands.md](references\u002Fcognito-troubleshooting-commands.md) - pre-flight command listings + safety checks\n\n## Domain\n\nAWS CloudOps \u002F Cognito Identity, Authentication and Authorization\nDiagnostics, User Pool, Identity Pool, Federated Identities, Lambda\nTriggers, and Social \u002F SAML Provider Integration.\n\n## AWS documentation\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n","# Cognito Auth Troubleshooter\n\n## Quick start\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Mindset\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Philosophy\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Expert heuristic\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Quick reference — symptom triage table\n\n| Symptom phrase \u002F error | Most likely layer | First probe |\n|---|---|---|\n| `NotAuthorizedException`, `error: invalid_client` | APP_CLIENT_SECRET | `describe-user-pool-client` (ClientSecret present? Client sending secret?) |\n| `NotAuthorizedException`, `error: invalid_grant` | TOKEN_REFRESH \u002F AUTH_FLOW | `describe-user-pool-client` (ExplicitAuthFlows), check token expiry |\n| `redirect_mismatch`, `invalid_redirect_uri` | HOSTED_UI_REDIRECT | `describe-user-pool-client` (CallbackURLs) vs app config |\n| `UserLambdaValidationException` | PRE_TOKEN_GEN_LAMBDA \u002F CUSTOM_SENDER_LAMBDA | CloudWatch Logs for the trigger Lambda |\n| `GetCredentialsForIdentity` -> `NotAuthorizedException` | IDENTITY_POOL_ROLE \u002F IDENTITY_POOL_TRUST | `get-identity-pool-roles` + IAM role trust policy |\n| Social login button -> blank page or error | SOCIAL_PROVIDER \u002F SOCIAL_REDIRECT | User Pool domain + app client callback + provider redirect URIs |\n| SAML login -> `InvalidSAMLRole` or loop | SAML_PROVIDER \u002F SAML_CERTIFICATE | Provider metadata, certificate fingerprint |\n| MFA code rejected | MFA_CONFIG \u002F MFA_TOTP \u002F MFA_SMS | User Pool MFA config, user's MFA settings |\n| Password rejected on signup\u002Freset | PASSWORD_POLICY | User Pool Policies (password policy) |\n| Custom attribute write -> `ResourceNotFoundException` or silent failure | CUSTOM_ATTRIBUTE | `describe-user-pool` (SchemaAttributes, `Mutable` flag) |\n| Domain prefix -> `DomainAlreadyExists` | DOMAIN_PREFIX | `describe-user-pool-domain` \u002F `list-user-pool-domains` |\n| TLS error on auth domain | TLS_CERTIFICATE | Certificate status, ACM, CloudFront distribution |\n\n## Pre-flight: pool state and gather-info gate\n\nBefore running symptom-specific probes, gather the canonical pool\nconfiguration and short-circuit on pool states that mimic authentication\nfailures. Misclassifying these produces hours of debugging for a problem\nthat is not an auth problem.\n\n### Account-wide pre-flight commands\n\nMoved verbatim to [references\u002Fcognito-troubleshooting-commands.md](references\u002Fcognito-troubleshooting-commands.md) - load on demand (see References below).\n\n### Pool-state short-circuit\n\n| Configuration field | Effect on diagnosis |\n|---|---|\n| `UserPool.MfaConfiguration: OFF` but user has `SMS_MFA` or `SOFTWARE_AUTH_MFA` setting | MFA was enabled per-user but pool-level MFA is OFF. The user's MFA setting is stale; clear it via `admin-set-user-mfa-preference`. |\n| `UserPool.LambdaConfig.PreTokenGeneration` points at a Lambda that does not exist | Every sign-in fails with `UserLambdaValidationException`. Verify the Lambda ARN resolves. |\n| `UserPool.Domain` empty but hosted UI is used | The hosted UI requires a domain prefix or custom domain. Without it, the auth domain returns 404. |\n| `UserPoolClient.ClientSecret` empty but client sends `client_secret` | PUBLIC client sending a secret that does not exist. The SDK returns `Unauthorized`. |\n| `UserPoolClient.ClientSecret` present but client omits it | CONFIDENTIAL client omitting the secret. The SDK returns `invalid_client`. |\n\n### Alias \u002F app client pre-flight\n\n| Field | Effect |\n|---|---|\n| `UserPoolClient.ExplicitAuthFlows` does not include `ALLOW_USER_PASSWORD_AUTH` | Direct `AdminInitiateAuth` with `USER_PASSWORD_AUTH` flow fails. Add the flow to the allow list. |\n| `UserPoolClient.AllowedOAuthFlows` empty | OAuth\u002FOIDC flows (code grant, implicit) via hosted UI fail. Configure `[\"code\", \"implicit\"]`. |\n| Multiple app clients, caller uses the wrong one | Each app client has its own callback URLs, flows, and scopes. Verify the caller's `client_id` matches the intended app client. |\n| `UserPoolClient.PreventUserExistenceErrors: true` | Cognito returns generic `NotAuthorizedException` instead of `UserNotFoundException`. This is a security feature, not a bug. |\n\nIf the input is malformed (missing UserPoolId or AppClientId, absent\nsymptom description, no error string for offline diagnosis), emit:\n\n```text\nTARGET: \u003Cpool-id \u002F client-id or unknown>\nVERDICT: INSUFFICIENT_DATA\nREASON: Input is missing required context — at minimum a symptom\n  description (the error string or observed behaviour) and the\n  UserPoolId or AppClientId.\nLAYER: UNKNOWN\nEVIDENCE:\n  - Missing: \u003Clist specific missing fields>\nREMEDIATION: Re-prompt the operator for: (1) the exact error string or\n  observed symptom, (2) the UserPoolId and AppClientId, (3) the auth\n  flow being used (hosted UI code grant, implicit, USER_PASSWORD_AUTH,\n  USER_SRP_AUTH, etc.), and (4) for identity pool issues, the\n  IdentityPoolId and whether the user is authenticated or\n  unauthenticated.\n```\n\n## Process — Diagnostic decision tree (apply in symptom order)\n\nThe diagnostic tree is symptom-driven. Pick the entry point based on the\nobserved symptom, then walk the layer-specific probes in order. Each layer\nends with either a positive root-cause confirmation (failing probe that\nmatches the symptom) or a pass that moves to the next layer. **Never emit\nROOT_CAUSE_IDENTIFIED without a failing probe that matches the symptom.**\n\n### Step 0: Non-obvious behaviours that change diagnosis\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 1: Symptom entry — pick the diagnostic branch\n\nMap the symptom to a branch and jump to that branch's section. If the\nsymptom matches none of the categories, route to Step 13 (INSUFFICIENT_DATA).\n\n| Symptom | Branch |\n|---|---|\n| `NotAuthorizedException` on sign-in, `invalid_client` | Step 2 — App client |\n| `NotAuthorizedException` on sign-in, `invalid_grant` \u002F wrong flow | Step 3 — Auth flow |\n| `redirect_mismatch` \u002F `invalid_redirect_uri` | Step 4 — Hosted UI redirect |\n| `InvalidGrantException` on refresh token exchange | Step 5 — Token refresh |\n| `UserLambdaValidationException` on sign-in | Step 6 — Lambda triggers |\n| `GetCredentialsForIdentity` -> `NotAuthorizedException` | Step 7 — Identity pool |\n| Social login button -> error \u002F blank page | Step 8 — Social provider |\n| SAML login -> `SAMLResponseDoesNotMatch` \u002F loop | Step 9 — SAML provider |\n| MFA code rejected \u002F cannot set up MFA | Step 10 — MFA |\n| Password rejected on signup or reset | Step 11 — Password policy |\n| Custom attribute write fails | Step 12 — Custom attribute |\n| `DomainAlreadyExistsException` | Step 12b — Domain prefix |\n| TLS error on auth domain | Step 12c — TLS certificate |\n| None of the above | Step 13 — INSUFFICIENT_DATA |\n\n### Step 2: App client secret — CONFIDENTIAL vs PUBLIC\n\nSymptom: `NotAuthorizedException` with `error: invalid_client` or a\ngeneric \"authentication failed\" on the very first API call. The error\nfires before any user credentials are validated, because the client\nitself is not authenticated.\n\n```bash\naws cognito-idp describe-user-pool-client \\\n  --user-pool-id \u003Cpool-id> --client-id \u003Cclient-id> --output json | \\\n  jq '{ClientId, ClientSecret: (.ClientSecret != null), ExplicitAuthFlows, AllowedOAuthFlows}'\n```\n\nKey checks:\n\n| Condition | Diagnosis |\n|---|---|\n| `ClientSecret` present (non-null) but client does not send it | CONFIDENTIAL client used as PUBLIC. Fix: include the secret in the token exchange, or recreate the client with `GenerateClientSecret: false`. |\n| `ClientSecret` absent (null) but client sends a fabricated secret | PUBLIC client sent a secret. Fix: remove the `client_secret` parameter from the SDK call. |\n| `ClientSecret` present and client sends it, but value is wrong | Stale secret (rotated or recreated). Fix: retrieve the current secret via `describe-user-pool-client` and update the application config. |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: APP_CLIENT_SECRET`. Fix:\neither align the client type with the usage (PUBLIC or CONFIDENTIAL)\nor ensure the correct secret value is used.\n\n### Step 3: Auth flow — wrong or missing flow\n\nMoved verbatim to [references\u002Fcognito-auth-flow-reference.md](references\u002Fcognito-auth-flow-reference.md) - load on demand (see References below).\n\n### Step 4: Hosted UI redirect mismatch\n\nSymptom: `redirect_mismatch` or `invalid_redirect_uri` from the hosted\nUI `\u002Foauth2\u002Fauthorize` endpoint. The browser URL shows the Cognito\nauth domain with an error parameter.\n\n```bash\naws cognito-idp describe-user-pool-client \\\n  --user-pool-id \u003Cpool-id> --client-id \u003Cclient-id> --output json | \\\n  jq '.CallbackURLs'\n```\n\nCross-reference each `CallbackURL` against the `redirect_uri` parameter\nthe application sends:\n\n| Mismatch type | Example | Fix |\n|---|---|---|\n| Trailing slash | App: `https:\u002F\u002Fapp.example.com\u002Fcallback\u002F` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | Add the trailing-slash variant to `CallbackURLs` (or remove it from the app) |\n| Scheme | App: `http:\u002F\u002Fapp.example.com\u002Fcallback` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | Match the scheme (prefer HTTPS) |\n| Port | App: `https:\u002F\u002Fapp.example.com:8443\u002Fcallback` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | Add the port to `CallbackURLs` |\n| Path | App: `https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | Add the exact path |\n| Case | App: `https:\u002F\u002FApp.Example.Com\u002Fcallback` vs Config: `https:\u002F\u002Fapp.example.com\u002Fcallback` | DNS is case-insensitive but Cognito compares case-sensitively; normalise |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: HOSTED_UI_REDIRECT`. Fix:\nupdate the app client `CallbackURLs` to include the exact redirect URI\nthe application sends.\n\n### Step 5: Token refresh failure\n\nMoved verbatim to [references\u002Fcognito-auth-flow-reference.md](references\u002Fcognito-auth-flow-reference.md) - load on demand (see References below).\n\n### Step 6: Lambda trigger errors\n\nSymptom: `UserLambdaValidationException` on sign-in, sign-up, forgot\npassword, or any auth flow. The error message typically contains the\nLambda's exception type and message.\n\n```bash\naws cognito-idp describe-user-pool \\\n  --user-pool-id \u003Cpool-id> --output json | \\\n  jq '.UserPool.LambdaConfig'\n\naws logs filter-log-events \\\n  --log-group-name \u002Faws\u002Flambda\u002F\u003Ctrigger-name> \\\n  --start-time $(date -d '-30 minutes' +%s)000 \\\n  --filter-pattern '\"ERROR\" OR \"Exception\" OR \"Task timed out\"' \\\n  --output json\n```\n\nCommon trigger failure patterns:\n\n| Trigger | Error | Common cause |\n|---|---|---|\n| `PreTokenGeneration` | `UserLambdaValidationException` on every sign-in | Lambda throws on malformed event, response exceeds 100 KB, or response shape does not match `{claimsToAddOrOverride, claimsToSuppress}` |\n| `PreSignUp` | `UserLambdaValidationException` on sign-up | Lambda does not return `event.response.autoConfirmUser` or returns wrong shape |\n| `PostConfirmation` | `UserLambdaValidationException` after confirmation | Lambda times out calling downstream (e.g., DynamoDB, SES) |\n| `CustomMessage` | `UserLambdaValidationException` on verification email | Lambda returns empty `event.response.emailMessage` or missing `emailSubject` |\n| `DefineAuthChallenge` \u002F `CreateAuthChallenge` \u002F `VerifyAuthChallenge` | Custom auth flow fails | State machine logic error in the trigger sequence |\n| `CustomSMSSender` \u002F `CustomEmailSender` | `InvalidParameterException` | KMS key missing or Lambda cannot decrypt; Lambda does not return the expected `response.smsMessage` \u002F `response.emailMessage` |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: PRE_TOKEN_GEN_LAMBDA` (or\nthe trigger-specific layer). Fix: address the Lambda error (code fix,\ntimeout increase, IAM permission for downstream calls).\n\n### Step 7: Identity pool role assumption failure\n\nSymptom: `GetCredentialsForIdentity` returns `NotAuthorizedException`\nor `AccessDenied`. The User Pool login succeeded (JWT issued) but the\nIdentity Pool cannot exchange the token for AWS credentials.\n\n```bash\naws cognito-identity get-identity-pool-roles \\\n  --identity-pool-id \u003Cidentity-pool-id> --output json\n\n# Check the role trust policy\nROLE_NAME=$(echo \u003Crole-arn> | cut -d\u002F -f2)\naws iam get-role --role-name \u003Crole-name> --output json | \\\n  jq '.Role.AssumeRolePolicyDocument'\n```\n\nKey checks for the trust policy:\n\n| Condition | Expected value |\n|---|---|\n| `Principal` | `\"cognito-identity.amazonaws.com\"` |\n| `Action` | `\"sts:AssumeRoleWithWebIdentity\"` (or `\"sts:AssumeRoleWithWebIdentity\"` in newer policies) |\n| `Condition.StringEquals[\"cognito-identity.amazonaws.com:aud\"]` | Must match the Identity Pool ID |\n| `Condition.StringEquals[\"cognito-identity.amazonaws.com:amr\"]` (unauth role) | Must contain `\"unauth\"` |\n| `Condition.StringEquals[\"cognito-identity.amazonaws.com:amr\"]` (auth role) | Must contain `\"authenticated\"` or a provider-specific value |\n\nCommon failure patterns:\n\n| Pattern | Cause |\n|---|---|\n| `aud` condition references a different (old) identity pool ID | Trust policy not updated after pool recreation. Fix: update the condition. |\n| `amr` condition missing for unauthenticated role | Unauthenticated access denied. Fix: add `\"unauth\"` to the `amr` condition. |\n| Role does not exist or was deleted | `get-identity-pool-roles` shows a role ARN that IAM cannot find. Fix: recreate the role with the correct trust policy. |\n| RoleMapping type is `Token` but provider is not configured | The identity pool does not have the User Pool as a configured provider. Fix: add the Cognito User Pool as an identity provider. |\n| `RoleMappings` has no rules and `Roles` is empty | No roles configured at all. Fix: set both `Roles` (auth + unauth) and `RoleMappings`. |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: IDENTITY_POOL_TRUST` (trust\npolicy) or `IDENTITY_POOL_ROLE` (role missing or misconfigured).\n\n### Step 8: Social provider misconfiguration\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 9: SAML provider certificate mismatch\n\nSymptom: SAML login returns `SAMLResponseDoesNotMatch`,\n`InvalidSAMLRole`, or the login loops between the IdP and Cognito.\n\n```bash\naws cognito-idp describe-identity-provider \\\n  --user-pool-id \u003Cpool-id> --provider-name \u003Csaml-provider-name> --output json | \\\n  jq '.ProviderDetails'\n\n# If using metadata URL, verify it is reachable:\ncurl -sI \u003Cmetadata-url> | head -5\n```\n\nKey checks:\n\n| Check | Expected |\n|---|---|\n| `ProviderType` | `SAML` |\n| `ProviderDetails.MetadataURL` or `MetadataFile` | URL must be reachable and return valid XML; file must be base64-encoded XML |\n| Certificate in metadata | Must match the IdP's current signing certificate; expired or rotated certificates cause `SAMLResponseDoesNotMatch` |\n| `attribute_mapping` | Maps SAML attributes (e.g., `email`) to User Pool attributes |\n| IdP-side Audience \u002F Entity ID | Must be the Cognito User Pool domain (e.g., `https:\u002F\u002F\u003Cdomain>.auth.\u003Cregion>.amazoncognito.com\u002Fsaml2\u002Fidpresponse`) |\n| IdP-side NameID format | Cognito expects `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` by default |\n\nCommon failure patterns:\n\n| Pattern | Cause |\n|---|---|\n| `SAMLResponseDoesNotMatch` | Certificate in metadata does not match the signing certificate used by the IdP. Fix: re-import updated metadata. |\n| Login loop (IdP -> Cognito -> IdP) | The `RelayState` or `InResponseTo` does not match, or Cognito cannot find the user based on the NameID. Fix: check the NameID format and user lookup attribute. |\n| `InvalidSAMLRole` | SAML response references a role ARN that does not exist or is not in the IdP's role mapping. Fix: update the role mapping. |\n| Metadata URL unreachable from Cognito | Cognito fetches the metadata at login time. If the URL is internal or rate-limited, logins fail intermittently. Fix: use `MetadataFile` instead of `MetadataURL`. |\n\n**Verdict:** ROOT_CAUSE_IDENTIFIED, `LAYER: SAML_CERTIFICATE` (cert\nmismatch) or `SAML_PROVIDER` (metadata \u002F mapping issue).\n\n### Step 10: MFA issues\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 11: Password policy violations\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 12: Custom attribute write permissions\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 12b: Domain prefix conflict\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 12c: TLS certificate issues\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n### Step 13: INSUFFICIENT_DATA\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## Output format\n\n```text\nTARGET: \u003Cpool-id \u002F client-id \u002F provider name>\nVERDICT: ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA\nREASON: \u003C1-2 sentences naming the failed layer and the failing probe>\nLAYER: \u003CAPP_CLIENT_CONFIG | APP_CLIENT_SECRET | AUTH_FLOW |\n        TOKEN_REFRESH | TOKEN_REVOCATION | HOSTED_UI_REDIRECT |\n        CUSTOM_ATTRIBUTE | PRE_TOKEN_GEN_LAMBDA |\n        IDENTITY_POOL_ROLE | IDENTITY_POOL_TRUST |\n        SOCIAL_PROVIDER | SOCIAL_REDIRECT |\n        SAML_PROVIDER | SAML_CERTIFICATE |\n        MFA_CONFIG | MFA_TOTP | MFA_SMS |\n        PASSWORD_POLICY | ACCOUNT_RECOVERY |\n        CUSTOM_SENDER_LAMBDA | DOMAIN_PREFIX |\n        TLS_CERTIFICATE | UNKNOWN>\nEVIDENCE:\n  - \u003Cobserved symptom — error string or behaviour>\n  - \u003Cfailing probe — command and its output that confirms the cause>\n  - \u003Cpassing probes — layers ruled out>\nREMEDIATION:\n  1. \u003Cspecific action with CLI command>\n  2. \u003Cverification command after the fix>\nCONFIRM: Before executing any state-changing CLI, emit and await operator\n  approval: \"CONFIRM: About to \u003Caction> on \u003Cpool \u002F client> in \u003Cregion>.\n  Proceed? (yes\u002Fno)\"\n```\n\n### Worked example — Hosted UI redirect mismatch\n\n```text\nTARGET: us-east-1_AbCdEf123 \u002F client 1ab2cd3ef4gh5ij6lmn7opq8rs\nVERDICT: ROOT_CAUSE_IDENTIFIED\nREASON: The application sends redirect_uri=https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback\n  but the app client CallbackURLs lists only\n  https:\u002F\u002Fapp.example.com\u002Fcallback. The path \u002Fauth\u002Fcallback is missing\n  from the configured callback list (Step 4).\nLAYER: HOSTED_UI_REDIRECT\nEVIDENCE:\n  - Symptom: all users see redirect_mismatch error after entering\n    credentials on the hosted UI. The browser address bar shows\n    redirect_uri=https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback.\n  - Probe: aws cognito-idp describe-user-pool-client returns\n    CallbackURLs: [\"https:\u002F\u002Fapp.example.com\u002Fcallback\"] — the path\n    \u002Fauth\u002Fcallback is absent.\n  - Passing: ClientSecret is null (PUBLIC client, no secret mismatch);\n    ExplicitAuthFlows includes ALLOW_REFRESH_TOKEN_AUTH and\n    ALLOW_USER_SRP_AUTH; no Lambda triggers configured.\nREMEDIATION:\n  1. Add the correct callback URL to the app client:\n     aws cognito-idp update-user-pool-client \\\n       --user-pool-id us-east-1_AbCdEf123 \\\n       --client-id 1ab2cd3ef4gh5ij6lmn7opq8rs \\\n       --callback-urls \"https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback\" \"https:\u002F\u002Fapp.example.com\u002Fcallback\"\n  2. Verify by navigating to the hosted UI authorize endpoint with\n     redirect_uri=https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback — the redirect\n     should succeed without error.\nCONFIRM: Before updating the app client, emit and await:\n  \"CONFIRM: About to add https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback to\n   CallbackURLs on client 1ab2cd3ef4gh5ij6lmn7opq8rs. Proceed? (yes\u002Fno)\"\n```\n\n### Worked example — Identity pool unauthenticated role trust policy\n\nMoved verbatim to [references\u002Fworked-examples.md](references\u002Fworked-examples.md) - load on demand (see References below).\n\n### Worked example — Pre-token-generation Lambda error\n\nMoved verbatim to [references\u002Fworked-examples.md](references\u002Fworked-examples.md) - load on demand (see References below).\n\n## Anti-Patterns — NEVER\n\n- NEVER declare ROOT_CAUSE_IDENTIFIED without a failing probe that\n  matches the symptom. A \"process of elimination\" diagnosis erodes\n  operator trust when the real cause is elsewhere.\n\n- NEVER assume the app client is PUBLIC because the application is a\n  SPA. Check `describe-user-pool-client` for `ClientSecret` presence.\n  Many SPAs use CONFIDENTIAL clients with a server-side proxy for the\n  secret; others are truly PUBLIC. The diagnostic is driven by config,\n  not by application type.\n\n- NEVER add a `client_secret` to a PUBLIC client call. The secret does\n  not exist; sending a fabricated value produces `Unauthorized`. If the\n  client was created without a secret, the SDK must not send one.\n\n- NEVER compare the `redirect_uri` loosely. Scheme, host, port, path,\n  and trailing slash must all match exactly. A single character\n  difference (including case) produces `redirect_mismatch`.\n\n- NEVER assume the identity pool role trust policy is correct because\n  \"it worked before.\" Pool IDs change when pools are recreated; the\n  `aud` condition must reference the CURRENT pool ID. Always verify\n  the trust policy's `aud` condition against the live pool ID.\n\n- NEVER forget the `amr` condition for the unauthenticated role. The\n  trust policy must include\n  `\"ForAnyValue:StringLike\": {\"cognito-identity.amazonaws.com:amr\": \"unauth\"}`\n  for unauthenticated access. Omitting it silently breaks guest access.\n\n- NEVER assume the pre-token-generation Lambda is correct because the\n  code \"hasn't changed.\" If the upstream IdP stopped sending a claim\n  that the Lambda reads, the Lambda throws even though the Lambda code\n  is unchanged. Always check CloudWatch Logs for the trigger.\n\n- NEVER update a SAML provider's metadata without verifying the\n  certificate. If the IdP rotated its signing certificate and the new\n  metadata has the correct cert, updating fixes the issue. But if the\n  metadata still has the OLD cert, updating is a no-op and the logins\n  still fail.\n\n- NEVER use `MfaConfiguration: ON` at pool level and then try to\n  disable MFA per-user. Pool-level `ON` enforces MFA for all users.\n  To make MFA optional, use `MfaConfiguration: OPTIONAL`.\n\n- NEVER recreate a User Pool to \"fix\" a config issue without exporting\n  users first. Pool recreation changes the Pool ID, invalidating all\n  existing JWTs, app client IDs, identity pool mappings, and trigger\n  Lambda ARNs. Always attempt to fix the config in place.\n\n- NEVER assume a custom attribute can be updated after sign-up. Check\n  the `Mutable` flag. If `Mutable: false`, the attribute is write-once\n  at sign-up time. Making it mutable requires creating a new pool with\n  the corrected attribute.\n\n- NEVER set `RefreshTokenValidity` without checking\n  `TokenValidityUnits.RefreshToken`. A value of `30` could be 30\n  seconds, 30 minutes, 30 hours, or 30 days depending on the unit.\n  The default unit is `days`.\n\n- NEVER send the `client_secret` in the browser for a PUBLIC client.\n  Even if the client has a secret (misconfigured CONFIDENTIAL client\n  used by a SPA), the secret should be proxied through a backend, not\n  exposed in client-side code.\n\n## Pre-flight safety checks (run before any state-changing CLI)\n\nMoved verbatim to [references\u002Fcognito-troubleshooting-commands.md](references\u002Fcognito-troubleshooting-commands.md) - load on demand (see References below).\n\n## Remediation guidance\n\nMoved verbatim to [references\u002Ferror-handling.md](references\u002Ferror-handling.md) - load on demand (see References below).\n\n## Deep reference: Cognito authentication layer model\n\nMoved verbatim to [references\u002Fcognito-auth-flow-reference.md](references\u002Fcognito-auth-flow-reference.md) - load on demand (see References below).\n\n## Recent AWS features (2024-2026)\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n## References (load on demand)\n\n- [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - quick-start detail, mindset\u002Fphilosophy\u002Fexpert heuristics, Step 0 gotchas, extended branches (Steps 8-13), recent AWS features\n- [references\u002Fworked-examples.md](references\u002Fworked-examples.md) - secondary worked examples (identity pool trust, pre-token Lambda)\n- [references\u002Ferror-handling.md](references\u002Ferror-handling.md) - remediation guidance per layer\n- [references\u002Fcognito-auth-flow-reference.md](references\u002Fcognito-auth-flow-reference.md) - auth-flow layer model, token lifecycle, Steps 3\u002F5 detail\n- [references\u002Fcognito-troubleshooting-commands.md](references\u002Fcognito-troubleshooting-commands.md) - pre-flight command listings + safety checks\n\n## Domain\n\nAWS CloudOps \u002F Cognito Identity, Authentication and Authorization\nDiagnostics, User Pool, Identity Pool, Federated Identities, Lambda\nTriggers, and Social \u002F SAML Provider Integration.\n\n## AWS documentation\n\nMoved verbatim to [references\u002Fadvanced-patterns.md](references\u002Fadvanced-patterns.md) - load on demand (see References below).\n\n",{"name":5,"license":15,"metadata":24,"description":7,"compatibility":44},{"tags":25,"phase":26,"author":27,"domain":28,"family":29,"version":30,"keywords":31,"task_type":32,"complexity":33,"entry_point":34,"skill_class":35,"when_to_use":36,"requires_llm":37,"verdict_shape":38,"when_not_to_use":39,"lifecycle_status":40,"invocation_schema":41,"supports_pipeline":37,"invocation_example":42,"activation_triggers":43},"cognito, security, troubleshooting, authentication, user-pool, identity-pool, hosted-ui, jwt, saml, mfa","2","Jacky Chan — AWS Community Builder","aws-cloudops","Security","0.1.0","Cognito, User Pool, Identity Pool, authentication, authorization, token refresh, access token, ID token, refresh token, JWT, JWKS, hosted UI, callback URL, redirect URI, app client, client secret, PUBLIC client, CONFIDENTIAL client, auth flow, ALLOW_USER_PASSWORD_AUTH, ALLOW_USER_SRP_AUTH, ALLOW_REFRESH_TOKEN_AUTH, custom attributes, pre-token-generation, Lambda trigger, identity pool, federated identities, unauthenticated role, trust policy, cognito-identity, social provider, Google, Facebook, SignInWithApple, SAML, certificate mismatch, MFA, TOTP, SMS MFA, password policy, account recovery, custom sender, domain prefix, TLS certificate, troubleshooting","troubleshoot","high","false","capability","Diagnosing a Cognito authentication failure (sign-in error, token refresh failure, hosted UI redirect mismatch, social or SAML provider error, MFA setup or bypass, identity pool role assumption failure, pre-token-generation Lambda error, domain prefix conflict, TLS error), walking a symptom to the failed layer with verify and fix commands, validating why a user cannot authenticate, or triaging a \"users cannot log in\" page where the root cause may be app client config, auth flow, token lifecycle, hosted UI, provider, trigger Lambda, or identity pool role trust — not necessarily the application code.","true","ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA","Application-level session management beyond Cognito token exchange (use the application framework's auth docs), API Gateway custom authorizer debugging (use apigateway-http-troubleshooter), root-cause analysis of the user's device or browser (use browser developer tools and device logs), or IAM policy authoring for the authenticated\u002Funauthenticated roles (use iam-least-privilege-advisor). This skill diagnoses Cognito authentication-time failures; it does not audit steady-state security posture or tune application session logic.","active","Input: either (a) a symptom description (error message, observed behaviour, \"users cannot log in\", \"token refresh returns InvalidGrantException\"), optionally paired with the User Pool \u002F Identity Pool configuration and recent CloudWatch logs, OR (b) a UserPoolId \u002F IdentityPoolId plus client context (AppClientId, auth flow, provider name, observed error) for live-account diagnosis. Output: a deterministic TARGET\u002FVERDICT\u002FREASON\u002FLAYER\u002FEVIDENCE\u002FREMEDIATION block where VERDICT ∈ {ROOT_CAUSE_IDENTIFIED, INSUFFICIENT_DATA} and LAYER ∈ {APP_CLIENT_CONFIG, APP_CLIENT_SECRET, AUTH_FLOW, TOKEN_REFRESH, TOKEN_REVOCATION, HOSTED_UI_REDIRECT, CUSTOM_ATTRIBUTE, PRE_TOKEN_GEN_LAMBDA, IDENTITY_POOL_ROLE, IDENTITY_POOL_TRUST, SOCIAL_PROVIDER, SOCIAL_REDIRECT, SAML_PROVIDER, SAML_CERTIFICATE, MFA_CONFIG, MFA_TOTP, MFA_SMS, PASSWORD_POLICY, ACCOUNT_RECOVERY, CUSTOM_SENDER_LAMBDA, DOMAIN_PREFIX, TLS_CERTIFICATE, UNKNOWN}.","# Minimal valid input (offline symptom classification):\nSymptom: \"Users report 'redirect_mismatch' error after entering credentials\non the Cognito hosted UI. The callback URL in the browser bar shows\nhttps:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback but the app client is configured\nwith https:\u002F\u002Fapp.example.com\u002Fcallback.\"\nUserPoolId: us-east-1_AbCdEf123\nAppClientId: 1ab2cd3ef4gh5ij6lmn7opq8rs\nAuthFlow: code grant (hosted UI)\nDomain: auth.example.com (Cognito domain prefix)\nHostedUI callback URLs: https:\u002F\u002Fapp.example.com\u002Fcallback\nExpected callback (from app config): https:\u002F\u002Fapp.example.com\u002Fauth\u002Fcallback","Cognito authentication failed, Cognito NotAuthorizedException, Cognito UserLambdaValidationException, Cognito InvalidParameterException, Cognito redirect mismatch, Cognito hosted UI callback URL, Cognito token refresh failed, Cognito refresh token expired, Cognito InvalidGrantException, Cognito pre-token-generation Lambda error, Cognito identity pool role assumption, Cognito unauthenticated role, cognito-identity amazonaws com, Cognito social provider Google, Cognito Facebook login, Cognito SignInWithApple, Cognito SAML provider, Cognito SAML certificate, Cognito MFA setup failed, Cognito MFA bypass, Cognito password policy, Cognito custom attributes, Cognito domain prefix, Cognito TLS certificate, troubleshoot Cognito authentication","Agent runtime that reads SKILL.md (Claude Code, Cursor, Windsurf, Codex, Gemini). Offline symptom classification works from pasted error messages and user-pool configuration. Live-account diagnosis uses aws cognito-idp describe-user-pool, describe-user-pool-client, describe-identity-pool, get-identity-pool-roles, list-user-pools, list-user-pool-clients, aws lambda get-function \u002F get-policy (for triggers), aws iam simulate-principal-policy, aws cloudtrail lookup-events, aws logs...","main","eeace51bd5dd1db2030729d83eeab988861553aa","skills\u002Fcognito-auth-troubleshooter",0,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills","https:\u002F\u002Fgithub.com\u002Fjhkchan","CTO & Co-Founder @Beever-AI  & @votee. CAISP. AWS Community Builder. Organizer@GDGCloudHK. MongoDB Champion. Technopreneur + Infornographer.","2026-09-24 08:54:10",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add jhkchan\u002Faws-agent-skills --skill cognito-auth-troubleshooter",{"tool":59,"command":60},"bunx","bunx skills add jhkchan\u002Faws-agent-skills --skill cognito-auth-troubleshooter",{"tool":62,"command":63},"pnpm","pnpm dlx skills add jhkchan\u002Faws-agent-skills --skill cognito-auth-troubleshooter","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002FSKILL.md",true,[67,73,77,81,85,89,93,97,101,105,109,113,117,120,124,128,132,136,140,144],{"path":68,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":71,"sourceHtmlUrl":72},"eval\u002Ftest-cases.yaml","REFERENCE","参考文档",9907,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Feval\u002Ftest-cases.yaml",{"path":74,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":75,"sourceHtmlUrl":76},"evals\u002Fbaselines\u002Fapp-client-secret-public-flow.md",694,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fbaselines\u002Fapp-client-secret-public-flow.md",{"path":78,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":79,"sourceHtmlUrl":80},"evals\u002Fbaselines\u002Fhosted-ui-callback-mismatch.md",693,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fbaselines\u002Fhosted-ui-callback-mismatch.md",{"path":82,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":83,"sourceHtmlUrl":84},"evals\u002Fbaselines\u002Fidentity-pool-unauth-role-trust.md",715,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fbaselines\u002Fidentity-pool-unauth-role-trust.md",{"path":86,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":87,"sourceHtmlUrl":88},"evals\u002Fbaselines\u002Fpre-token-gen-lambda-attribute-missing.md",739,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fbaselines\u002Fpre-token-gen-lambda-attribute-missing.md",{"path":90,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":91,"sourceHtmlUrl":92},"evals\u002Fbaselines\u002Fsaml-provider-cert-mismatch.md",714,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fbaselines\u002Fsaml-provider-cert-mismatch.md",{"path":94,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":95,"sourceHtmlUrl":96},"evals\u002Feval_config.yaml",2058,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Feval_config.yaml",{"path":98,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":99,"sourceHtmlUrl":100},"evals\u002Fevals.json",4981,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fevals.json",{"path":102,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":103,"sourceHtmlUrl":104},"evals\u002Fprompts\u002Fapp-client-secret-public-flow.md",1316,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fprompts\u002Fapp-client-secret-public-flow.md",{"path":106,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":107,"sourceHtmlUrl":108},"evals\u002Fprompts\u002Fhosted-ui-callback-mismatch.md",1272,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fprompts\u002Fhosted-ui-callback-mismatch.md",{"path":110,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":111,"sourceHtmlUrl":112},"evals\u002Fprompts\u002Fidentity-pool-unauth-role-trust.md",2000,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fprompts\u002Fidentity-pool-unauth-role-trust.md",{"path":114,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":115,"sourceHtmlUrl":116},"evals\u002Fprompts\u002Fpre-token-gen-lambda-attribute-missing.md",1356,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fprompts\u002Fpre-token-gen-lambda-attribute-missing.md",{"path":118,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":107,"sourceHtmlUrl":119},"evals\u002Fprompts\u002Fsaml-provider-cert-mismatch.md","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fevals\u002Fprompts\u002Fsaml-provider-cert-mismatch.md",{"path":121,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":122,"sourceHtmlUrl":123},"examples\u002FREADME.md",5481,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fexamples\u002FREADME.md",{"path":125,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":126,"sourceHtmlUrl":127},"references\u002Fadvanced-patterns.md",26791,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Freferences\u002Fadvanced-patterns.md",{"path":129,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":130,"sourceHtmlUrl":131},"references\u002Fcognito-auth-flow-reference.md",16931,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Freferences\u002Fcognito-auth-flow-reference.md",{"path":133,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":134,"sourceHtmlUrl":135},"references\u002Fcognito-troubleshooting-commands.md",10791,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Freferences\u002Fcognito-troubleshooting-commands.md",{"path":137,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":138,"sourceHtmlUrl":139},"references\u002Ferror-handling.md",4096,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Freferences\u002Ferror-handling.md",{"path":141,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":142,"sourceHtmlUrl":143},"references\u002Fworked-examples.md",3115,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Freferences\u002Fworked-examples.md",{"path":145,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":146,"sourceHtmlUrl":147},"skill.usf.yaml",4630,"https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fcognito-auth-troubleshooter\u002Fskill.usf.yaml",[149,156,163,170,177,184],{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":155,"publishedAt":19},"01M7ADVD60X4PCAPKSE58P9NDC","xray-tracing-deployer","Deploys AWS X-Ray distributed tracing with production-grade configuration: X-Ray daemon deployment (EC2 systemd, ECS sidecar, EKS DaemonSet, Lambda built-in), SDK instrumentation (Java, Python, Node.js, Go, .NET) with annotations and metadata, sampling rules (default reservoir + rate vs custom rules with URL \u002F method \u002F service-name predicates), service map generation, trace query and retrieval, groups and insights, CloudWatch ServiceLens integration, IAM permissions (PutTraceSegments, GetSamplingRules), and latest features (Lambda Powertools tracing, OpenTelemetry \u002F ADOT Collector support, W3C trace context). Emits a READY_TO_DEPLOY checklist with every configuration item verified. Use when enabling X-Ray on a new application, adding tracing to ECS \u002F EKS \u002F Lambda, validating a sampling configuration, or generating daemon deployment CLI and IaC templates. Triggers: X-Ray, distributed tracing, X-Ray daemon, sampling rules, service map, X-Ray SDK, OpenTelemetry, ADOT, Lambda Powertools, CloudWatch ServiceLens.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxray-tracing-deployer\u002FSKILL.md",[],[],{"skillNo":157,"name":158,"nameZh":6,"description":159,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":160,"categories":161,"keywords":162,"publishedAt":19},"01M7ADTVJ7DCBM9CB1FY51GH7J","wellarchitected-workload-auditor","Audits AWS Well-Architected Tool workloads for review staleness, per-pillar high-risk issue counts, milestone tracking gaps, and remediation plan completeness. Emits a deterministic verdict (STALE_REVIEW | HIGH_RISK | CONFIG_GAP | OK) per workload with per-pillar risk breakdown, milestone trend analysis, and specific remediation. Use when reviewing Well-Architected workloads, checking WA review freshness, auditing high-risk issues per pillar, validating milestone coverage, or tracking remediation plans.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwellarchitected-workload-auditor\u002FSKILL.md",[],[],{"skillNo":164,"name":165,"nameZh":6,"description":166,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":167,"categories":168,"keywords":169,"publishedAt":19},"01M7ADT59G6FTTNZYHT2QRPNNP","wellarchitected-review-operator","Operates AWS Well-Architected Tool reviews end-to-end — creates workloads, runs pillar reviews (operational excellence, security, reliability, performance, cost optimization, sustainability, Prosperity), answers questions with risk-tier rationale, generates reports and improvement plans, creates milestones, and integrates with Trusted Advisor and Well-Architected Labs. Runs deterministic pre-checks (workload existence, lens availability, pillar coverage), emits the exact update-answer \u002F get-consolidated-report CLI behind a CONFIRM gate, and verifies risk-tier transitions. Emits READY | BLOCKED | COMPLETED. Use when creating a workload, answering pillar questions, generating an improvement plan, creating a milestone, or integrating with Trusted Advisor. Triggers: well-architected tool, well architected review, workload review, pillar, operational excellence, security, reliability, performance, cost optimization, sustainability, prosperity, improvement plan, milestone, trusted advisor.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwellarchitected-review-operator\u002FSKILL.md",[],[],{"skillNo":171,"name":172,"nameZh":6,"description":173,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":174,"categories":175,"keywords":176,"publishedAt":19},"01M7ADSH5JA9QHNPPHQCD7EVA7","wafv2-web-acl-deployer","Provisions AWS WAFv2 Web ACLs with correct production defaults: scope selection (CLOUDFRONT vs REGIONAL), managed rule groups (AWSManagedRulesCommonRuleSet, SQLiRuleSet, LinuxRuleSet, WindowsRuleSet, IPReputationList, BotControlRuleSet, AmazonIpReputationList, ATP), custom rules (byte match, IP set, regex pattern, geo match, size constraint, rate-based), rule priority ordering, logging destinations (Kinesis Firehose, CloudWatch Logs, S3), resource association (ALB, API Gateway, CloudFront), rate-based rules with aggregate keys (IP, forwarded IP), Challenge and CAPTCHA actions, and account takeover prevention. Emits a READY_TO_DEPLOY checklist. Use when creating a Web ACL, attaching managed rules, configuring rate limiting, enabling WAF logging, associating a Web ACL with an ALB\u002FAPI Gateway\u002FCloudFront, or configuring CAPTCHA\u002FChallenge actions. Triggers: create WAF Web ACL, WAFv2, managed rule groups, WAF rate limiting, WAF logging, WAF CAPTCHA, WAF Challenge action, bot control, ATP managed rules.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwafv2-web-acl-deployer\u002FSKILL.md",[],[],{"skillNo":178,"name":179,"nameZh":6,"description":180,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":181,"categories":182,"keywords":183,"publishedAt":19},"01M7ADRYFAT8R73FBNCHRC573X","wafv2-web-acl-auditor","Audits AWS WAFv2 Web ACL configurations to determine whether the ACL provides effective protection: default-action posture (Allow vs Block), managed-rule-group coverage gaps, rule effectiveness (BLOCK vs COUNT, shadow\u002Fbypass rules, stale exclusions), rate-based rule correctness, logging and visibility configuration, and text-transformation bypass vectors. Emits a deterministic verdict per Web ACL. Use when reviewing a WAFv2 Web ACL for security posture, checking managed-rule coverage, validating rate-limit configuration, auditing WAF logging, or hardening a WAF before production deployment. Triggers: WAF, WAFv2, Web ACL, managed rule group, AWSManagedRules, rate-based rule, CAPTCHA, Challenge, OverrideAction, Count mode, forwarded IP, Bot Control, ATP, text transformation, WAF logging, WAF visibility, OWASP, SQLi, XSS, RFI.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwafv2-web-acl-auditor\u002FSKILL.md",[],[],{"skillNo":185,"name":186,"nameZh":6,"description":187,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":188,"categories":189,"keywords":190,"publishedAt":19},"01M7ADR8W7G72JX4KFGN03QK8Q","waf-rule-deployer","Provisions AWS WAFv2 rule sets with production defaults: Web ACL creation (CloudFront scope in us-east-1 vs Regional scope), rule groups (managed vs custom) with capacity planning in WCU (Web ACL Capacity Units, 1500 default per ACL), managed rule groups (AWSManagedRulesCommonRuleSet, AWSManagedRulesSQLiRuleSet, AWSManagedRulesAmazonIpReputationList, AWSManagedRulesLinuxRuleSet, AWSManagedRulesWindowsRuleSet, AWSManagedRulesUnixRuleSet), custom rules (byte-match, regex pattern set, geo-match, rate-based), IP set and regex pattern set resources, rule priority ordering (lowest number evaluated first), action types (allow, block, count, CAPTCHA, Challenge), bot control managed rule group, account takeover. Triggers: create WAF rule, WAF managed rule group, WAF custom rule, WAF byte match, WAF geo match, WAF rate based rule, WAF IP set, WAF regex pattern set, WAF WCU budget, WAF CloudFront ACL, WAF logging Kinesis Firehose, WAF bot control, WAF ATP, WAF label matching, WAF Challenge action, WAF CAPTCHA.","https:\u002F\u002Fgithub.com\u002Fjhkchan\u002Faws-agent-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwaf-rule-deployer\u002FSKILL.md",[],[]]