cognito-auth-troubleshooter
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/Facebook/Apple) 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.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-24
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- cognito-auth-troubleshooter
- license
- Apache-2.0
- metadata
- { "tags": "cognito, security, troubleshooting, authentication, user-pool, identity-pool, hosted-ui, jwt, saml, mfa", "phase": "2", "author": "Jacky Chan — AWS Community Builder", "domain": "aws-cloudops", "family": "Security", "version": "0.1.0", "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", "task_type": "troubleshoot", "complexity": "high", "entry_point": "false", "skill_class": "capability", "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.", "requires_llm": "true", "verdict_shape": "ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA", "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/unauthenticated 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.", "lifecycle_status": "active", "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 / Identity Pool configuration and recent CloudWatch logs, OR (b) a UserPoolId / IdentityPoolId plus client context (AppClientId, auth flow, provider name, observed error) for live-account diagnosis. Output: a deterministic TARGET/VERDICT/REASON/LAYER/EVIDENCE/REMEDIATION 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}.", "supports_pipeline": "true", "invocation_example": "# 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://app.example.com/auth/callback but the app client is configured\nwith https://app.example.com/callback.\"\nUserPoolId: us-east-1_AbCdEf123\nAppClientId: 1ab2cd3ef4gh5ij6lmn7opq8rs\nAuthFlow: code grant (hosted UI)\nDomain: auth.example.com (Cognito domain prefix)\nHostedUI callback URLs: https://app.example.com/callback\nExpected callback (from app config): https://app.example.com/auth/callback", "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" }
- description
- 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/Facebook/Apple) 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.
- compatibility
- 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 / get-policy (for triggers), aws iam simulate-principal-policy, aws cloudtrail lookup-events, aws logs...
02 资源文件 20
- 参考文档eval/test-cases.yaml9.7 KB
- 参考文档evals/baselines/app-client-secret-public-flow.md694 B
- 参考文档evals/baselines/hosted-ui-callback-mismatch.md693 B
- 参考文档evals/baselines/identity-pool-unauth-role-trust.md715 B
- 参考文档evals/baselines/pre-token-gen-lambda-attribute-missing.md739 B
- 参考文档evals/baselines/saml-provider-cert-mismatch.md714 B
- 参考文档evals/eval_config.yaml2.0 KB
- 参考文档evals/evals.json4.9 KB
- 参考文档evals/prompts/app-client-secret-public-flow.md1.3 KB
- 参考文档evals/prompts/hosted-ui-callback-mismatch.md1.2 KB
- 参考文档evals/prompts/identity-pool-unauth-role-trust.md2.0 KB
- 参考文档evals/prompts/pre-token-gen-lambda-attribute-missing.md1.3 KB
- 参考文档evals/prompts/saml-provider-cert-mismatch.md1.2 KB
- 参考文档examples/README.md5.4 KB
- 参考文档references/advanced-patterns.md26.2 KB
- 参考文档references/cognito-auth-flow-reference.md16.5 KB
- 参考文档references/cognito-troubleshooting-commands.md10.5 KB
- 参考文档references/error-handling.md4.0 KB
- 参考文档references/worked-examples.md3.0 KB
- 参考文档skill.usf.yaml4.5 KB
03 SKILL.md 正文
Cognito Auth Troubleshooter
Quick start
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Mindset
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Philosophy
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Expert heuristic
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Quick reference — symptom triage table
| Symptom phrase / error | Most likely layer | First probe |
|---|---|---|
NotAuthorizedException, error: invalid_client |
APP_CLIENT_SECRET | describe-user-pool-client (ClientSecret present? Client sending secret?) |
NotAuthorizedException, error: invalid_grant |
TOKEN_REFRESH / AUTH_FLOW | describe-user-pool-client (ExplicitAuthFlows), check token expiry |
redirect_mismatch, invalid_redirect_uri |
HOSTED_UI_REDIRECT | describe-user-pool-client (CallbackURLs) vs app config |
UserLambdaValidationException |
PRE_TOKEN_GEN_LAMBDA / CUSTOM_SENDER_LAMBDA | CloudWatch Logs for the trigger Lambda |
GetCredentialsForIdentity -> NotAuthorizedException |
IDENTITY_POOL_ROLE / IDENTITY_POOL_TRUST | get-identity-pool-roles + IAM role trust policy |
| Social login button -> blank page or error | SOCIAL_PROVIDER / SOCIAL_REDIRECT | User Pool domain + app client callback + provider redirect URIs |
SAML login -> InvalidSAMLRole or loop |
SAML_PROVIDER / SAML_CERTIFICATE | Provider metadata, certificate fingerprint |
| MFA code rejected | MFA_CONFIG / MFA_TOTP / MFA_SMS | User Pool MFA config, user's MFA settings |
| Password rejected on signup/reset | PASSWORD_POLICY | User Pool Policies (password policy) |
Custom attribute write -> ResourceNotFoundException or silent failure |
CUSTOM_ATTRIBUTE | describe-user-pool (SchemaAttributes, Mutable flag) |
Domain prefix -> DomainAlreadyExists |
DOMAIN_PREFIX | describe-user-pool-domain / list-user-pool-domains |
| TLS error on auth domain | TLS_CERTIFICATE | Certificate status, ACM, CloudFront distribution |
Pre-flight: pool state and gather-info gate
Before running symptom-specific probes, gather the canonical pool configuration and short-circuit on pool states that mimic authentication failures. Misclassifying these produces hours of debugging for a problem that is not an auth problem.
Account-wide pre-flight commands
Moved verbatim to references/cognito-troubleshooting-commands.md - load on demand (see References below).
Pool-state short-circuit
| Configuration field | Effect on diagnosis |
|---|---|
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. |
UserPool.LambdaConfig.PreTokenGeneration points at a Lambda that does not exist |
Every sign-in fails with UserLambdaValidationException. Verify the Lambda ARN resolves. |
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. |
UserPoolClient.ClientSecret empty but client sends client_secret |
PUBLIC client sending a secret that does not exist. The SDK returns Unauthorized. |
UserPoolClient.ClientSecret present but client omits it |
CONFIDENTIAL client omitting the secret. The SDK returns invalid_client. |
Alias / app client pre-flight
| Field | Effect |
|---|---|
UserPoolClient.ExplicitAuthFlows does not include ALLOW_USER_PASSWORD_AUTH |
Direct AdminInitiateAuth with USER_PASSWORD_AUTH flow fails. Add the flow to the allow list. |
UserPoolClient.AllowedOAuthFlows empty |
OAuth/OIDC flows (code grant, implicit) via hosted UI fail. Configure ["code", "implicit"]. |
| 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. |
UserPoolClient.PreventUserExistenceErrors: true |
Cognito returns generic NotAuthorizedException instead of UserNotFoundException. This is a security feature, not a bug. |
If the input is malformed (missing UserPoolId or AppClientId, absent symptom description, no error string for offline diagnosis), emit:
TARGET: <pool-id / client-id or unknown>
VERDICT: INSUFFICIENT_DATA
REASON: Input is missing required context — at minimum a symptom
description (the error string or observed behaviour) and the
UserPoolId or AppClientId.
LAYER: UNKNOWN
EVIDENCE:
- Missing: <list specific missing fields>
REMEDIATION: Re-prompt the operator for: (1) the exact error string or
observed symptom, (2) the UserPoolId and AppClientId, (3) the auth
flow being used (hosted UI code grant, implicit, USER_PASSWORD_AUTH,
USER_SRP_AUTH, etc.), and (4) for identity pool issues, the
IdentityPoolId and whether the user is authenticated or
unauthenticated.
Process — Diagnostic decision tree (apply in symptom order)
The diagnostic tree is symptom-driven. Pick the entry point based on the observed symptom, then walk the layer-specific probes in order. Each layer ends with either a positive root-cause confirmation (failing probe that matches the symptom) or a pass that moves to the next layer. Never emit ROOT_CAUSE_IDENTIFIED without a failing probe that matches the symptom.
Step 0: Non-obvious behaviours that change diagnosis
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Step 1: Symptom entry — pick the diagnostic branch
Map the symptom to a branch and jump to that branch's section. If the symptom matches none of the categories, route to Step 13 (INSUFFICIENT_DATA).
| Symptom | Branch |
|---|---|
NotAuthorizedException on sign-in, invalid_client |
Step 2 — App client |
NotAuthorizedException on sign-in, invalid_grant / wrong flow |
Step 3 — Auth flow |
redirect_mismatch / invalid_redirect_uri |
Step 4 — Hosted UI redirect |
InvalidGrantException on refresh token exchange |
Step 5 — Token refresh |
UserLambdaValidationException on sign-in |
Step 6 — Lambda triggers |
GetCredentialsForIdentity -> NotAuthorizedException |
Step 7 — Identity pool |
| Social login button -> error / blank page | Step 8 — Social provider |
SAML login -> SAMLResponseDoesNotMatch / loop |
Step 9 — SAML provider |
| MFA code rejected / cannot set up MFA | Step 10 — MFA |
| Password rejected on signup or reset | Step 11 — Password policy |
| Custom attribute write fails | Step 12 — Custom attribute |
DomainAlreadyExistsException |
Step 12b — Domain prefix |
| TLS error on auth domain | Step 12c — TLS certificate |
| None of the above | Step 13 — INSUFFICIENT_DATA |
Step 2: App client secret — CONFIDENTIAL vs PUBLIC
Symptom: NotAuthorizedException with error: invalid_client or a
generic "authentication failed" on the very first API call. The error
fires before any user credentials are validated, because the client
itself is not authenticated.
aws cognito-idp describe-user-pool-client \
--user-pool-id <pool-id> --client-id <client-id> --output json | \
jq '{ClientId, ClientSecret: (.ClientSecret != null), ExplicitAuthFlows, AllowedOAuthFlows}'
Key checks:
| Condition | Diagnosis |
|---|---|
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. |
ClientSecret absent (null) but client sends a fabricated secret |
PUBLIC client sent a secret. Fix: remove the client_secret parameter from the SDK call. |
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. |
Verdict: ROOT_CAUSE_IDENTIFIED, LAYER: APP_CLIENT_SECRET. Fix:
either align the client type with the usage (PUBLIC or CONFIDENTIAL)
or ensure the correct secret value is used.
Step 3: Auth flow — wrong or missing flow
Moved verbatim to references/cognito-auth-flow-reference.md - load on demand (see References below).
Step 4: Hosted UI redirect mismatch
Symptom: redirect_mismatch or invalid_redirect_uri from the hosted
UI /oauth2/authorize endpoint. The browser URL shows the Cognito
auth domain with an error parameter.
aws cognito-idp describe-user-pool-client \
--user-pool-id <pool-id> --client-id <client-id> --output json | \
jq '.CallbackURLs'
Cross-reference each CallbackURL against the redirect_uri parameter
the application sends:
| Mismatch type | Example | Fix |
|---|---|---|
| Trailing slash | App: https://app.example.com/callback/ vs Config: https://app.example.com/callback |
Add the trailing-slash variant to CallbackURLs (or remove it from the app) |
| Scheme | App: http://app.example.com/callback vs Config: https://app.example.com/callback |
Match the scheme (prefer HTTPS) |
| Port | App: https://app.example.com:8443/callback vs Config: https://app.example.com/callback |
Add the port to CallbackURLs |
| Path | App: https://app.example.com/auth/callback vs Config: https://app.example.com/callback |
Add the exact path |
| Case | App: https://App.Example.Com/callback vs Config: https://app.example.com/callback |
DNS is case-insensitive but Cognito compares case-sensitively; normalise |
Verdict: ROOT_CAUSE_IDENTIFIED, LAYER: HOSTED_UI_REDIRECT. Fix:
update the app client CallbackURLs to include the exact redirect URI
the application sends.
Step 5: Token refresh failure
Moved verbatim to references/cognito-auth-flow-reference.md - load on demand (see References below).
Step 6: Lambda trigger errors
Symptom: UserLambdaValidationException on sign-in, sign-up, forgot
password, or any auth flow. The error message typically contains the
Lambda's exception type and message.
aws cognito-idp describe-user-pool \
--user-pool-id <pool-id> --output json | \
jq '.UserPool.LambdaConfig'
aws logs filter-log-events \
--log-group-name /aws/lambda/<trigger-name> \
--start-time $(date -d '-30 minutes' +%s)000 \
--filter-pattern '"ERROR" OR "Exception" OR "Task timed out"' \
--output json
Common trigger failure patterns:
| Trigger | Error | Common cause |
|---|---|---|
PreTokenGeneration |
UserLambdaValidationException on every sign-in |
Lambda throws on malformed event, response exceeds 100 KB, or response shape does not match {claimsToAddOrOverride, claimsToSuppress} |
PreSignUp |
UserLambdaValidationException on sign-up |
Lambda does not return event.response.autoConfirmUser or returns wrong shape |
PostConfirmation |
UserLambdaValidationException after confirmation |
Lambda times out calling downstream (e.g., DynamoDB, SES) |
CustomMessage |
UserLambdaValidationException on verification email |
Lambda returns empty event.response.emailMessage or missing emailSubject |
DefineAuthChallenge / CreateAuthChallenge / VerifyAuthChallenge |
Custom auth flow fails | State machine logic error in the trigger sequence |
CustomSMSSender / CustomEmailSender |
InvalidParameterException |
KMS key missing or Lambda cannot decrypt; Lambda does not return the expected response.smsMessage / response.emailMessage |
Verdict: ROOT_CAUSE_IDENTIFIED, LAYER: PRE_TOKEN_GEN_LAMBDA (or
the trigger-specific layer). Fix: address the Lambda error (code fix,
timeout increase, IAM permission for downstream calls).
Step 7: Identity pool role assumption failure
Symptom: GetCredentialsForIdentity returns NotAuthorizedException
or AccessDenied. The User Pool login succeeded (JWT issued) but the
Identity Pool cannot exchange the token for AWS credentials.
aws cognito-identity get-identity-pool-roles \
--identity-pool-id <identity-pool-id> --output json
# Check the role trust policy
ROLE_NAME=$(echo <role-arn> | cut -d/ -f2)
aws iam get-role --role-name <role-name> --output json | \
jq '.Role.AssumeRolePolicyDocument'
Key checks for the trust policy:
| Condition | Expected value |
|---|---|
Principal |
"cognito-identity.amazonaws.com" |
Action |
"sts:AssumeRoleWithWebIdentity" (or "sts:AssumeRoleWithWebIdentity" in newer policies) |
Condition.StringEquals["cognito-identity.amazonaws.com:aud"] |
Must match the Identity Pool ID |
Condition.StringEquals["cognito-identity.amazonaws.com:amr"] (unauth role) |
Must contain "unauth" |
Condition.StringEquals["cognito-identity.amazonaws.com:amr"] (auth role) |
Must contain "authenticated" or a provider-specific value |
Common failure patterns:
| Pattern | Cause |
|---|---|
aud condition references a different (old) identity pool ID |
Trust policy not updated after pool recreation. Fix: update the condition. |
amr condition missing for unauthenticated role |
Unauthenticated access denied. Fix: add "unauth" to the amr condition. |
| 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. |
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. |
RoleMappings has no rules and Roles is empty |
No roles configured at all. Fix: set both Roles (auth + unauth) and RoleMappings. |
Verdict: ROOT_CAUSE_IDENTIFIED, LAYER: IDENTITY_POOL_TRUST (trust
policy) or IDENTITY_POOL_ROLE (role missing or misconfigured).
Step 8: Social provider misconfiguration
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Step 9: SAML provider certificate mismatch
Symptom: SAML login returns SAMLResponseDoesNotMatch,
InvalidSAMLRole, or the login loops between the IdP and Cognito.
aws cognito-idp describe-identity-provider \
--user-pool-id <pool-id> --provider-name <saml-provider-name> --output json | \
jq '.ProviderDetails'
# If using metadata URL, verify it is reachable:
curl -sI <metadata-url> | head -5
Key checks:
| Check | Expected |
|---|---|
ProviderType |
SAML |
ProviderDetails.MetadataURL or MetadataFile |
URL must be reachable and return valid XML; file must be base64-encoded XML |
| Certificate in metadata | Must match the IdP's current signing certificate; expired or rotated certificates cause SAMLResponseDoesNotMatch |
attribute_mapping |
Maps SAML attributes (e.g., email) to User Pool attributes |
| IdP-side Audience / Entity ID | Must be the Cognito User Pool domain (e.g., https://<domain>.auth.<region>.amazoncognito.com/saml2/idpresponse) |
| IdP-side NameID format | Cognito expects urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress by default |
Common failure patterns:
| Pattern | Cause |
|---|---|
SAMLResponseDoesNotMatch |
Certificate in metadata does not match the signing certificate used by the IdP. Fix: re-import updated metadata. |
| 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. |
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. |
| 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. |
Verdict: ROOT_CAUSE_IDENTIFIED, LAYER: SAML_CERTIFICATE (cert
mismatch) or SAML_PROVIDER (metadata / mapping issue).
Step 10: MFA issues
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Step 11: Password policy violations
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Step 12: Custom attribute write permissions
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Step 12b: Domain prefix conflict
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Step 12c: TLS certificate issues
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Step 13: INSUFFICIENT_DATA
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
Output format
TARGET: <pool-id / client-id / provider name>
VERDICT: ROOT_CAUSE_IDENTIFIED | INSUFFICIENT_DATA
REASON: <1-2 sentences naming the failed layer and the failing probe>
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>
EVIDENCE:
- <observed symptom — error string or behaviour>
- <failing probe — command and its output that confirms the cause>
- <passing probes — layers ruled out>
REMEDIATION:
1. <specific action with CLI command>
2. <verification command after the fix>
CONFIRM: Before executing any state-changing CLI, emit and await operator
approval: "CONFIRM: About to <action> on <pool / client> in <region>.
Proceed? (yes/no)"
Worked example — Hosted UI redirect mismatch
TARGET: us-east-1_AbCdEf123 / client 1ab2cd3ef4gh5ij6lmn7opq8rs
VERDICT: ROOT_CAUSE_IDENTIFIED
REASON: The application sends redirect_uri=https://app.example.com/auth/callback
but the app client CallbackURLs lists only
https://app.example.com/callback. The path /auth/callback is missing
from the configured callback list (Step 4).
LAYER: HOSTED_UI_REDIRECT
EVIDENCE:
- Symptom: all users see redirect_mismatch error after entering
credentials on the hosted UI. The browser address bar shows
redirect_uri=https://app.example.com/auth/callback.
- Probe: aws cognito-idp describe-user-pool-client returns
CallbackURLs: ["https://app.example.com/callback"] — the path
/auth/callback is absent.
- Passing: ClientSecret is null (PUBLIC client, no secret mismatch);
ExplicitAuthFlows includes ALLOW_REFRESH_TOKEN_AUTH and
ALLOW_USER_SRP_AUTH; no Lambda triggers configured.
REMEDIATION:
1. Add the correct callback URL to the app client:
aws cognito-idp update-user-pool-client \
--user-pool-id us-east-1_AbCdEf123 \
--client-id 1ab2cd3ef4gh5ij6lmn7opq8rs \
--callback-urls "https://app.example.com/auth/callback" "https://app.example.com/callback"
2. Verify by navigating to the hosted UI authorize endpoint with
redirect_uri=https://app.example.com/auth/callback — the redirect
should succeed without error.
CONFIRM: Before updating the app client, emit and await:
"CONFIRM: About to add https://app.example.com/auth/callback to
CallbackURLs on client 1ab2cd3ef4gh5ij6lmn7opq8rs. Proceed? (yes/no)"
Worked example — Identity pool unauthenticated role trust policy
Moved verbatim to references/worked-examples.md - load on demand (see References below).
Worked example — Pre-token-generation Lambda error
Moved verbatim to references/worked-examples.md - load on demand (see References below).
Anti-Patterns — NEVER
-
NEVER declare ROOT_CAUSE_IDENTIFIED without a failing probe that matches the symptom. A "process of elimination" diagnosis erodes operator trust when the real cause is elsewhere.
-
NEVER assume the app client is PUBLIC because the application is a SPA. Check
describe-user-pool-clientforClientSecretpresence. Many SPAs use CONFIDENTIAL clients with a server-side proxy for the secret; others are truly PUBLIC. The diagnostic is driven by config, not by application type. -
NEVER add a
client_secretto a PUBLIC client call. The secret does not exist; sending a fabricated value producesUnauthorized. If the client was created without a secret, the SDK must not send one. -
NEVER compare the
redirect_uriloosely. Scheme, host, port, path, and trailing slash must all match exactly. A single character difference (including case) producesredirect_mismatch. -
NEVER assume the identity pool role trust policy is correct because "it worked before." Pool IDs change when pools are recreated; the
audcondition must reference the CURRENT pool ID. Always verify the trust policy'saudcondition against the live pool ID. -
NEVER forget the
amrcondition for the unauthenticated role. The trust policy must include"ForAnyValue:StringLike": {"cognito-identity.amazonaws.com:amr": "unauth"}for unauthenticated access. Omitting it silently breaks guest access. -
NEVER assume the pre-token-generation Lambda is correct because the code "hasn't changed." If the upstream IdP stopped sending a claim that the Lambda reads, the Lambda throws even though the Lambda code is unchanged. Always check CloudWatch Logs for the trigger.
-
NEVER update a SAML provider's metadata without verifying the certificate. If the IdP rotated its signing certificate and the new metadata has the correct cert, updating fixes the issue. But if the metadata still has the OLD cert, updating is a no-op and the logins still fail.
-
NEVER use
MfaConfiguration: ONat pool level and then try to disable MFA per-user. Pool-levelONenforces MFA for all users. To make MFA optional, useMfaConfiguration: OPTIONAL. -
NEVER recreate a User Pool to "fix" a config issue without exporting users first. Pool recreation changes the Pool ID, invalidating all existing JWTs, app client IDs, identity pool mappings, and trigger Lambda ARNs. Always attempt to fix the config in place.
-
NEVER assume a custom attribute can be updated after sign-up. Check the
Mutableflag. IfMutable: false, the attribute is write-once at sign-up time. Making it mutable requires creating a new pool with the corrected attribute. -
NEVER set
RefreshTokenValiditywithout checkingTokenValidityUnits.RefreshToken. A value of30could be 30 seconds, 30 minutes, 30 hours, or 30 days depending on the unit. The default unit isdays. -
NEVER send the
client_secretin the browser for a PUBLIC client. Even if the client has a secret (misconfigured CONFIDENTIAL client used by a SPA), the secret should be proxied through a backend, not exposed in client-side code.
Pre-flight safety checks (run before any state-changing CLI)
Moved verbatim to references/cognito-troubleshooting-commands.md - load on demand (see References below).
Remediation guidance
Moved verbatim to references/error-handling.md - load on demand (see References below).
Deep reference: Cognito authentication layer model
Moved verbatim to references/cognito-auth-flow-reference.md - load on demand (see References below).
Recent AWS features (2024-2026)
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
References (load on demand)
- references/advanced-patterns.md - quick-start detail, mindset/philosophy/expert heuristics, Step 0 gotchas, extended branches (Steps 8-13), recent AWS features
- references/worked-examples.md - secondary worked examples (identity pool trust, pre-token Lambda)
- references/error-handling.md - remediation guidance per layer
- references/cognito-auth-flow-reference.md - auth-flow layer model, token lifecycle, Steps 3/5 detail
- references/cognito-troubleshooting-commands.md - pre-flight command listings + safety checks
Domain
AWS CloudOps / Cognito Identity, Authentication and Authorization Diagnostics, User Pool, Identity Pool, Federated Identities, Lambda Triggers, and Social / SAML Provider Integration.
AWS documentation
Moved verbatim to references/advanced-patterns.md - load on demand (see References below).
04 同仓库更多 Skills
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 / method / 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 / 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 / EKS / 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.
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.
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 / 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.
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/API Gateway/CloudFront, or configuring CAPTCHA/Challenge 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.
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/bypass 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.
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.