Amazon Cognito Diagnostic and Troubleshooting Toolkit
A diagnostic and troubleshooting toolkit for Amazon Cognito that helps engineers identify authentication, MFA, OAuth, federation, token, Lambda trigger, delivery, Identity Pool, domain, WAF, Managed Login, and threat-protection issues. It supports targeted investigations, comprehensive health checks, redacted reports, S3 output, and CI/CD severity-based validation.
Overview
Command examples use
YOUR_SCRIPT_NAME.py as a placeholder. Replace it with the actual filename or path used in your environment before running any command.The
YOUR_SCRIPT_NAME.py script is a diagnostic, troubleshooting,
configuration-review, and security-assessment utility for Amazon
Cognito.It is designed to help engineers investigate Amazon Cognito user pools
and related AWS services without having to manually collect
configuration from multiple consoles and APIs.
The script can begin with a basic user pool configuration snapshot and
then run targeted or broad diagnostic checks for authentication, MFA,
app clients, OAuth, Lambda triggers, tokens, email and SMS delivery,
identity federation, identity pools, custom domains, AWS WAF, Managed
Login, threat logging, and other supporting services.
The script's own usage guidance recommends
--all-checks --redact as a
starting point when an engineer receives a new ticket and does not yet
know the cause of the problem. It also provides targeted commands for
common scenarios such as MFA failures, token validation errors, Lambda
trigger failures, redirect problems, federation failures, and delivery
issues.What Problem Does the Script Solve?
Amazon Cognito authentication problems can involve more than the user
pool itself.
A sign-in problem may be caused by:
- User pool configuration.
- App client configuration.
- MFA settings.
- A specific user's state.
- OAuth callback or logout URLs.
- Token configuration or JWKS availability.
- SAML or OIDC federation.
- Lambda triggers.
- IAM permissions or trust relationships.
- Amazon SES email configuration.
- Amazon SNS SMS configuration.
- A Cognito Identity Pool.
- A custom domain or ACM certificate.
- AWS WAF.
- Managed Login configuration.
- Threat protection or logging.
- CloudTrail events.
Troubleshooting these components manually can require moving between
several AWS consoles and collecting information from multiple APIs.
This script provides a single diagnostic workflow that can collect
and correlate much of that information into one report.
High-Level Workflow
The script follows this general process:
- Connect to the AWS account using the credentials available to the Python AWS SDK.
- Retrieve the Amazon Cognito user pool configuration.
- Enumerate app clients, identity providers, groups, resource servers, MFA configuration, risk configuration, domains, and other pool settings.
- Optionally inspect a specific user.
- Run the diagnostic modules selected by command-line options.
- Correlate Cognito configuration with related AWS services where required.
- Generate issues and recommendations.
- Optionally redact usernames and other report data.
- Write the result locally, display it as JSON or a human-readable summary, or upload it to Amazon S3.
- Optionally return a non-zero exit code when findings meet a configured severity threshold.
Main Diagnostic Areas
User Pool Configuration
The script collects core user pool settings including:
- User pool ID and ARN.
- Pool name and status.
- Cognito domain and custom domain.
- MFA configuration.
- Enabled MFA methods.
- Username and alias attributes.
- User schema.
- Password policy.
- Sign-in policy.
- WebAuthn configuration.
- User pool feature tier.
- Lambda trigger configuration.
- Email and SMS configuration.
- Account recovery configuration.
- Device configuration.
- deletion protection.
- User pool add-ons and advanced security configuration.
- Verification message configuration.
- Estimated number of users.
This provides an engineer with a baseline snapshot before deeper
troubleshooting begins.
Security Configuration Analysis
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --analyzeThe analysis checks for configuration and security concerns such as:
- MFA disabled or inconsistently configured.
- Passkey/WebAuthn configuration alignment.
- Weak password-policy settings.
- Excessive temporary-password validity.
- Advanced security posture.
- Deletion protection.
- Account recovery configuration.
- App client authentication flows.
- OAuth implicit flow.
- Token revocation.
- User-existence error protection.
- Attribute update verification.
- Custom resource-server scope alignment.
- Identity-provider attribute mappings.
The result includes severity-based findings and recommendations that can
be used during configuration reviews or support investigations.
Use Cases
Use Case 1 - New Cognito Support Case
Scenario: An engineer receives a Cognito support case but does not
yet know whether the problem is related to MFA, OAuth, federation,
Lambda, tokens, delivery, WAF, or another configuration.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --all-checks --redact--all-checks enables the script's broad diagnostic set, including
configuration analysis, MFA troubleshooting, Lambda inspection, URL
checks, token inspection, delivery checks, app-client comparison,
CloudTrail authentication events, domain inspection, WAF inspection,
federation inspection, Managed Login inspection, and threat-log
inspection.This is useful as a first-pass health assessment before deciding
which component requires deeper investigation.
Use Case 2 - A Specific User Cannot Sign In
Scenario: One user reports that authentication fails while other
users appear unaffected.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> <USERNAME> --analyze --mfa-troubleshootThe script can collect user-specific information such as:
- User status.
- Whether the user is enabled.
- MFA settings.
- Preferred MFA method.
- User attributes.
- Recent authentication events.
- Group membership.
- Remembered devices.
The script also attempts to resolve identifiers supplied as usernames,
email addresses, phone numbers, or preferred usernames.
This helps distinguish a user-specific problem from a pool-wide
configuration problem.
Use Case 3 - MFA Is Not Working
Scenario: A user is stuck in an MFA challenge, cannot receive an MFA
code, or has an unexpected MFA configuration.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> <USERNAME> --mfa-troubleshootThe script correlates pool-level MFA settings with user-level MFA state
and can help identify mismatches between configured and usable MFA
methods.
This can help investigate:
- MFA disabled at pool level.
- MFA enabled without an active method.
- Missing preferred MFA configuration.
- SMS-related configuration problems.
- User state preventing normal authentication.
- Passkey/WebAuthn alignment issues.
Use Case 4 - Lambda Trigger Is Blocking Authentication
Scenario: Cognito authentication fails with a trigger-related error
or Lambda errors appear during sign-in.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --lambda-inspectTo inspect a longer log window:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --lambda-inspect --log-hours 72The script can inspect Lambda trigger configuration and supporting
dependencies, including:
- Function configuration.
- IAM role information.
- Lambda resource policy.
- CloudWatch log events.
- CloudWatch metrics.
- KMS dependencies where applicable.
Custom log groups can also be supplied for deployments that do not use
the standard Lambda log-group naming convention.
Use Case 5 - Callback or Logout Redirect Failure
Scenario: Cognito Managed Login or the hosted login experience
returns a redirect error, or the browser does not return to the
application after authentication.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --check-urlsThe script evaluates registered callback and logout URLs and can test
their reachability.
This helps identify problems involving:
- Incorrect callback URLs.
- Incorrect logout URLs.
- Unreachable application endpoints.
- App-client configuration differences.
Use Case 6 - Token or JWKS Validation Failure
Scenario: An application reports that Cognito tokens cannot be
validated, the JWKS endpoint cannot be reached, or OIDC discovery is
failing.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --token-inspectThe token inspection covers areas such as:
- Cognito JWKS.
- OIDC discovery.
- Hosted login endpoints.
- Token-validity configuration.
A JWT can also be supplied for additional inspection:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --token-inspect --jwt <JWT>or:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --token-inspect --jwt-file token.txtThis is useful when application logs show signature, issuer, key,
discovery, or token-lifetime errors.
Use Case 7 - Email or SMS Codes Are Not Arriving
Scenario: Users are not receiving verification emails,
password-reset emails, or SMS messages.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --delivery-inspectFor deeper checks:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --delivery-deep-inspectThe script can correlate Cognito delivery configuration with supporting
services such as:
- Amazon SES.
- Amazon SNS.
- SMS caller-role configuration.
- SES sending identities.
- SNS sandbox state.
This helps determine whether the failure originates in Cognito
configuration or in the downstream delivery service.
Use Case 8 - SAML or OIDC Federation Is Failing
Scenario: Authentication through an enterprise SAML provider or OIDC
provider fails.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --federation-inspectFor OIDC providers, the script can inspect:
- Configured issuer.
- OIDC discovery endpoint.
- Discovery issuer consistency.
- Authorization endpoint.
- Token endpoint.
- JWKS URI.
- JWKS reachability and available keys.
For SAML providers, the script performs metadata-oriented diagnostics.
This helps determine whether the problem is related to the Cognito IdP
configuration, provider metadata, issuer configuration, or externally
reachable federation endpoints.
Use Case 9 - Identity Pool Does Not Issue AWS Credentials
Scenario: Users successfully authenticate but cannot obtain
temporary AWS credentials from a Cognito Identity Pool.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --identity-pool <IDENTITY_POOL_ID>The script can inspect:
- Identity Pool configuration.
- Cognito provider mapping.
- Associated user pool.
- App client alignment.
- Authenticated and unauthenticated IAM roles.
For deeper IAM trust analysis, use the Identity Pool deep inspection
option where appropriate.
This is useful for applications that use a Cognito User Pool for
authentication and a Cognito Identity Pool to obtain AWS credentials.
Use Case 10 - Custom Domain or Certificate Problem
Scenario: Cognito login through a custom domain fails or certificate
health is in question.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --domain-inspectThe script can inspect the Cognito domain configuration and ACM
certificate information, including certificate status and expiry
information.
This can help identify:
- Incorrect certificate region.
- Certificate expiry risk.
- Missing custom-domain certificate configuration.
- Domain configuration inconsistencies.
Use Case 11 - AWS WAF Protection Review
Scenario: A Cognito user pool is expected to be protected by AWS WAF
and an engineer wants to confirm the association and logging posture.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --waf-inspectThe script queries AWS WAF for the Web ACL associated with the Cognito
user pool and checks WAF logging configuration.
This can help answer:
- Is a Web ACL associated with the user pool?
- Which WAF rules are configured?
- Is WAF logging enabled?
- Is additional request-level security investigation required?
Use Case 12 - Managed Login Troubleshooting
Scenario: The Cognito Managed Login experience does not behave as
expected for one or more app clients.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --managed-login-inspectThe script can inspect Managed Login branding and app-client-related
configuration.
This is useful when investigating differences between app clients or
determining whether Managed Login configuration exists for the intended
client.
Use Case 13 - Threat Protection and Security Logging Review
Scenario: An engineer wants to determine whether Cognito
security-related logging and threat-protection configuration are
present.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --threat-log-inspectThe script inspects Cognito log-delivery configuration and related
threat/security settings.
This helps determine whether sufficient security telemetry exists for
further investigation.
Use Case 14 - Compare App Clients
Scenario: One application works but another application using the
same user pool fails.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --client-diffThe script compares app-client configurations.
This can expose differences in:
- Authentication flows.
- OAuth settings.
- Callback URLs.
- Logout URLs.
- Token configuration.
- Identity providers.
- Client security settings.
This is especially useful when two applications are expected to behave
identically but do not.
Use Case 15 - Investigate Recent Authentication Activity
Scenario: Authentication recently stopped working and an engineer
wants additional event context.
Use:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --cloudtrail-auth-eventsThe script uses CloudTrail lookup functionality to retrieve recent
Cognito-related authentication activity.
This can supplement Cognito configuration analysis with recent
control-plane or authentication-related event context available to the
script.
Use Case 16 - Live Authentication Test
Scenario: Static configuration looks correct, but the engineer needs
to determine whether authentication can actually complete.
The script provides an explicit live authentication test using options
such as:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--auth-test \
--auth-client-id <CLIENT_ID> \
--auth-username <USERNAME> \
--auth-password-env COGNITO_TEST_PASSWORDThis is intentionally separate from
--all-checks because it requires
credentials and performs a real authentication operation.Use dedicated test accounts and avoid exposing passwords directly on
command lines where possible.
Use Case 17 - Registration and Password-Recovery Testing
The script also contains explicit transaction-test capabilities for
workflows such as:
- Sign-up.
- Confirm sign-up.
- Forgot password.
- Confirm forgot password.
These operations are not included in
--all-checks because they
require explicit input and can change application state.They are useful when the problem is not merely configuration but whether
a particular Cognito transaction works end to end.
--all-checks
The script provides an
--all-checks shorthand for broad
non-credentialed diagnostics.It enables:
-
--analyze
-
--mfa-troubleshoot
-
--lambda-inspect
-
--check-urls
-
--token-inspect
-
--delivery-inspect
-
--delivery-deep-inspect
-
--client-diff
-
--cloudtrail-auth-events
-
--domain-inspect
-
--waf-inspect
-
--federation-inspect
-
--managed-login-inspect
-
--threat-log-inspect
The following are intentionally not automatically included:
-
--auth-test
-
--signup-test
-
--confirm-signup-test
-
--forgot-password-test
-
--confirm-forgot-password-test
-
--identity-pool
These require credentials, additional identifiers, or potentially
state-changing operations.
Recommended Support Workflow
Step 1 - Start With a Broad Assessment
For a new case:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> --all-checks --redact --output report.jsonThis provides a broad configuration and diagnostic report while reducing
the amount of customer-identifying data in the output.
Step 2 - Add a User When the Problem Is User-Specific
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> <USERNAME> \
--all-checks \
--redact \
--output user-report.jsonThis adds user-specific authentication, MFA, device, group, and event
information where available.
Step 3 - Add an Identity Pool When AWS Credential Issuance Is Involved
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--all-checks \
--identity-pool <IDENTITY_POOL_ID> \
--redact \
--output identity-report.jsonStep 4 - Use Transaction Tests Only When Required
If static diagnostics do not explain the failure, run the specific
authentication, registration, or recovery test needed for the scenario.
Do not use live transaction tests merely to collect configuration.
Customer-Safe Reporting
The script supports:
--redactThe purpose of this option is to reduce PII exposure in diagnostic
reports by replacing usernames with redacted identifiers.
For example:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> <USERNAME> \
--all-checks \
--redact \
--output customer-report.jsonThe script also supports direct S3 output:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--all-checks \
--redact \
--s3 my-bucket/cognito-reports/The script's documented S3 behavior uses server-side encryption with
SSE-S3.
Important: Redaction should be treated as a data-minimization
feature, not as permission to publish reports without review. Engineers
should still inspect the generated report before sharing it outside the
intended support audience.
Human-Readable Summary Output
The default output is JSON, but the script also supports a
human-readable summary format.
Example:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--all-checks \
--output-format summaryThis can be useful when the engineer wants a quick terminal-oriented
assessment instead of the complete structured report.
JSON remains useful for:
- Automation.
- Archiving.
- Comparing reports.
- S3 storage.
- Programmatic processing.
- Support evidence.
CI and Automation
The script supports severity-based pipeline behavior through:
--fail-on <SEVERITY>Example:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--analyze \
--fail-on HIGHSupported severity values include:
-
CRITICAL
-
HIGH
-
MEDIUM
-
LOW
-
WARNING
-
ERROR
-
INFO
This allows the script to be used as a configuration-quality gate rather
than only as an interactive troubleshooting utility.
Possible CI use cases include:
- Detecting security-relevant Cognito configuration drift.
- Reviewing configuration after infrastructure changes.
- Checking app-client settings before release.
- Failing a pipeline when a high-severity issue is detected.
- Generating a diagnostic artifact for later investigation.
Example Scenario - Login Works for One Application but Fails for Another
An organization has two applications using the same Cognito user pool.
Application A works correctly, while Application B fails after
authentication.
A useful workflow is:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--client-diff \
--check-urls \
--token-inspect \
--federation-inspectThe engineer can use the combined report to determine whether the
applications differ in app-client configuration, redirect URLs, token
settings, or federation configuration.
Example Scenario - Users Suddenly Stop Receiving Password Reset Codes
Run:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--delivery-inspect \
--delivery-deep-inspectThe script can help separate:
- Cognito email configuration.
- SES identity problems.
- SES account configuration.
- SMS configuration.
- SNS sandbox restrictions.
- Cognito recovery configuration.
This reduces the need to troubleshoot each service independently.
Example Scenario - Enterprise SSO Stops Working
Run:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--federation-inspect \
--check-urls \
--token-inspect \
--domain-inspectThis combines federation metadata checks with the surrounding Cognito
login path.
The engineer can investigate whether the failure originates from the
external identity provider, Cognito federation configuration, callback
configuration, token endpoints, or the Cognito domain.
Example Scenario - Authentication Is Being Blocked by a Lambda Trigger
Run:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--lambda-inspect \
--cloudtrail-auth-events \
--analyzeThis provides configuration context plus Lambda and recent-event
information, helping the engineer determine whether the authentication
problem is caused by a trigger, IAM configuration, a Lambda dependency,
or the Cognito configuration itself.
Example Scenario - Security Review Before Production
Run:
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--all-checks \
--redact \
--output production-readiness.jsonThe resulting report can support a review of:
- MFA.
- Password policy.
- Authentication flows.
- OAuth configuration.
- Token settings.
- User attribute protection.
- Advanced security configuration.
- Federation.
- WAF.
- Domain and certificate configuration.
- Threat/security logging.
- Lambda integrations.
- Delivery dependencies.
The script should be considered a diagnostic and configuration-review
aid, not a replacement for a complete application security assessment,
penetration test, or organization-specific security standard.
AWS Services Used by the Diagnostic Workflow
Depending on the selected checks, the script can interact with:
- Amazon Cognito User Pools.
- Amazon Cognito Identity Pools.
- AWS Lambda.
- Amazon CloudWatch Logs.
- Amazon CloudWatch metrics.
- AWS Identity and Access Management.
- Amazon SNS.
- Amazon SES.
- AWS Certificate Manager.
- AWS CloudTrail.
- AWS Key Management Service.
- AWS WAF.
- Amazon S3.
Not every command requires access to every service. IAM permissions can
therefore be scoped to the diagnostic modules that an engineer intends
to use.
IAM Considerations
The script requires read permissions for the Cognito configuration and
additional permissions for optional deep-inspection modules.
Examples include:
cognito-idp:DescribeUserPool
cognito-idp:ListUserPoolClients
cognito-idp:DescribeUserPoolClient
cognito-idp:DescribeUserPoolDomain
cognito-idp:ListIdentityProviders
cognito-idp:DescribeIdentityProvider
cognito-idp:GetUserPoolMfaConfig
cognito-idp:ListResourceServers
cognito-idp:ListGroups
cognito-idp:DescribeRiskConfiguration
cognito-identity:DescribeIdentityPool
cognito-identity:GetIdentityPoolRoles
lambda:GetFunctionConfiguration
lambda:GetPolicy
logs:FilterLogEvents
iam:GetRole
sns:GetSMSSandboxAccountStatus
ses:GetIdentityVerificationAttributes
ses:GetAccountSendingEnabled
acm:DescribeCertificate
cloudwatch:GetMetricStatistics
cloudtrail:LookupEvents
kms:DescribeKey
wafv2:GetWebACLForResource
wafv2:GetLoggingConfiguration
s3:PutObjectLive transaction tests require additional Cognito API permissions
appropriate to the operation being tested.
Apply least privilege and grant only the permissions required for
the checks that will actually be executed.
Operational Safety
Most inspection modes are intended to be non-destructive.
However, the script also provides explicit transaction tests.
Treat these differently:
Read-oriented diagnostics
- Configuration analysis.
- MFA troubleshooting.
- Lambda inspection.
- URL checks.
- Token inspection.
- Delivery inspection.
- Client comparison.
- CloudTrail inspection.
- Domain inspection.
- WAF inspection.
- Federation inspection.
- Managed Login inspection.
- Threat-log inspection.
Potentially state-changing or credential-dependent tests
- Authentication tests.
- Sign-up tests.
- Confirm-sign-up tests.
- Forgot-password tests.
- Confirm-forgot-password tests.
Use dedicated test identities for transaction testing where possible.
What the Script Does Not Replace
The script is broad, but it should not be treated as a replacement for:
- Application penetration testing.
- Full AWS account security assessment.
- IAM Access Analyzer review.
- Continuous SIEM monitoring.
- Application code review.
- Browser-side OAuth/PKCE implementation testing.
- External IdP administration.
- Full network troubleshooting.
- Organization-specific compliance validation.
Its primary purpose is to accelerate Amazon Cognito diagnosis by
bringing configuration, security posture, user state, federation, and
supporting AWS service evidence into one repeatable workflow.
Recommended Default Commands
New support case
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--all-checks \
--redact \
--output cognito-report.jsonSpecific affected user
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> <USERNAME> \
--all-checks \
--redact \
--output cognito-user-report.jsonSecurity configuration review
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--analyze \
--waf-inspect \
--federation-inspect \
--managed-login-inspect \
--threat-log-inspectCI configuration gate
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--analyze \
--fail-on HIGHCustomer-safe S3 support report
python3 YOUR_SCRIPT_NAME.py <USER_POOL_ID> \
--all-checks \
--redact \
--s3 my-bucket/cognito-reports/Summary
The script provides a single Amazon Cognito troubleshooting and
configuration-assessment toolkit for engineers who need to move
quickly from a user symptom to the underlying configuration or
dependency.
Instead of examining Cognito, Lambda, IAM, SES, SNS, CloudWatch,
CloudTrail, ACM, WAF, federation metadata, and Identity Pools
independently, the script brings those checks into a repeatable
command-line workflow.
Its strongest use cases are:
- New Cognito support-case triage.
- User login and MFA troubleshooting.
- App-client and OAuth configuration analysis.
- Token and JWKS troubleshooting.
- Lambda trigger investigation.
- Email and SMS delivery troubleshooting.
- SAML and OIDC federation troubleshooting.
- Identity Pool credential troubleshooting.
- Custom-domain and certificate review.
- WAF association and logging review.
- Managed Login troubleshooting.
- Threat/security logging review.
- Security configuration assessment.
- CI-based configuration checks.
- Redacted diagnostic report generation for support handoff.
The result is a faster, more consistent troubleshooting process with a
structured report that can be retained, compared, automated, or shared
with the appropriate support audience.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article