Skip to content

Troubleshooting Guide

Complete troubleshooting guide for common issues with the AWS Cognito Authoriser.

Quick Diagnostics

Check System Status

# Verify installation
cogauth --version
cogadmin --version

# Check configuration
cogauth status

# Test AWS connectivity
aws sts get-caller-identity

Debug Mode

# Enable detailed logging
export BOTO_DEBUG=1
export LOG_LEVEL=DEBUG
cogauth login -u test-user

Common Issues

Installation Issues

Command Not Found: cogauth or cogadmin

Symptoms:

$ cogauth --help
bash: cogauth: command not found

Solutions:

  1. Verify Installation:
pip show aws-cognito-auth
pip list | grep aws-cognito-auth
  1. Reinstall Package:
pip uninstall aws-cognito-auth
pip install -e .
  1. Check PATH:
which python
python -m pip show aws-cognito-auth
  1. Use Full Path:
python -m aws_cognito_auth.client --help
python -m aws_cognito_auth.admin --help

Import Errors

Symptoms:

ModuleNotFoundError: No module named 'aws_cognito_auth'

Solutions:

  1. Check Python Version:
python --version  # Should be 3.9+
  1. Install in Virtual Environment:
python -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate     # Windows
pip install -e .
  1. Install Dependencies:
pip install boto3 click botocore

Configuration Issues

Missing Configuration

Symptoms:

Error: Missing required configuration. Please run 'cogauth configure' first.

Solutions:

  1. Run Interactive Configuration:
cogauth configure
  1. Check Configuration File:
cat ~/.cognito-cli-config.json
  1. Set Environment Variables:
export COGNITO_USER_POOL_ID="us-east-1_xxxxxxxxx"
export COGNITO_CLIENT_ID="your-client-id"
export COGNITO_IDENTITY_POOL_ID="us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export AWS_REGION="us-east-1"

Invalid Configuration Format

Symptoms:

JSONDecodeError: Expecting property name enclosed in double quotes

Solutions:

  1. Validate JSON Syntax:
python -m json.tool ~/.cognito-cli-config.json
  1. Fix Common JSON Errors:
  2. Use double quotes for strings
  3. Remove trailing commas

  4. Escape backslashes

  5. Recreate Configuration:

rm ~/.cognito-cli-config.json
cogauth configure

Authentication Issues

Invalid Username or Password

Symptoms:

Error: Invalid username or password

Solutions:

  1. Verify User Exists:
aws cognito-idp admin-get-user --user-pool-id us-east-1_xxxxxxxxx --username test-user
  1. Check Password Requirements:
  2. Verify password meets User Pool policy

  3. Check if password reset is required

  4. Test with Different User:

cogauth login -u different-user

User Pool Configuration Error

Symptoms:

Error: User pool us-east-1_xxxxxxxxx does not exist or is not accessible

Solutions:

  1. Verify User Pool ID:
aws cognito-idp describe-user-pool --user-pool-id us-east-1_xxxxxxxxx
  1. Check Region:
aws configure get region
export AWS_REGION=us-east-1
  1. Verify AWS Credentials:
aws sts get-caller-identity

App Client Configuration Error

Symptoms:

Error: App client does not exist or authentication flow not enabled

Solutions:

  1. Check App Client:
aws cognito-idp describe-user-pool-client --user-pool-id us-east-1_xxxxxxxxx --client-id your-client-id
  1. Verify Authentication Flows:
  2. Enable ALLOW_USER_PASSWORD_AUTH

  3. Enable ALLOW_REFRESH_TOKEN_AUTH

  4. Update Client Configuration:

aws cognito-idp update-user-pool-client --user-pool-id us-east-1_xxxxxxxxx --client-id your-client-id --explicit-auth-flows ALLOW_USER_PASSWORD_AUTH ALLOW_REFRESH_TOKEN_AUTH

Identity Pool Issues

Identity Pool Configuration Error

Symptoms:

Error: Identity pool us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx does not exist

Solutions:

  1. Verify Identity Pool:
aws cognito-identity describe-identity-pool --identity-pool-id "us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  1. Check Authentication Providers:
aws cognito-identity get-identity-pool-configuration --identity-pool-id "us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  1. Set Up Identity Pool:
cogadmin setup-identity-pool

AssumeRoleWithWebIdentity Access Denied

Symptoms:

Error: User is not authorized to perform: sts:AssumeRoleWithWebIdentity

Solutions:

  1. Check Role Trust Policy:
aws iam get-role --role-name Cognito_IdentityPoolAuth_Role
  1. Update Trust Policy:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "cognito-identity.amazonaws.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "cognito-identity.amazonaws.com:aud": "us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                },
                "ForAnyValue:StringLike": {
                    "cognito-identity.amazonaws.com:amr": "authenticated"
                }
            }
        }
    ]
}

Lambda Proxy Issues

Lambda Function Not Found

Symptoms:

Error: Lambda function 'cognito-credential-proxy' not found. Please deploy it first using cogadmin lambda deploy

Solutions:

  1. Deploy Lambda Function:
cogadmin lambda deploy --create-user
  1. Check Function Exists:
aws lambda get-function --function-name cognito-credential-proxy
  1. Skip Lambda Proxy:
cogauth login -u test-user --no-lambda-proxy

Lambda Permission Denied

Symptoms:

Error: User is not authorized to perform: lambda:InvokeFunction

Solutions:

  1. Add Lambda Permission to Role:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "lambda:InvokeFunction",
            "Resource": "arn:aws:lambda:*:*:function:cognito-credential-proxy"
        }
    ]
}
  1. Apply Policy:
cogadmin role apply-policy --policy-file lambda-invoke-policy.json --policy-name LambdaInvokePolicy

Lambda Function Error

Symptoms:

Error: Lambda function execution failed

Solutions:

  1. Check Lambda Logs:
aws logs tail /aws/lambda/cognito-credential-proxy --follow
  1. Check Environment Variables:
aws lambda get-function-configuration --function-name cognito-credential-proxy
  1. Update Lambda Code:
cogadmin lambda deploy --access-key-id AKIA... --secret-access-key ...

Common Setup Issues and Solutions

Issue: "User is not authorized to perform: sts:TagSession"

Cause: The long-lived role's trust policy doesn't include sts:TagSession action.

Solution: Update the trust policy to include both "sts:AssumeRole" and "sts:TagSession" in the Action array.

Issue: "User is not authorized to perform: sts:AssumeRole on resource"

Cause: Either the IAM user doesn't have permission, or the role's trust policy doesn't allow the user.

Solution: 1. Verify the IAM user has the CognitoCredentialProxyAccess policy 2. Verify the long-lived role's trust policy includes the correct user ARN

Issue: Lambda function logs show "Missing required environment variable"

Cause: Lambda environment variables are not configured.

Solution: Set all three environment variables (IAM_USER_ACCESS_KEY_ID, IAM_USER_SECRET_ACCESS_KEY, DEFAULT_ROLE_ARN) in the Lambda function configuration.

Issue: "Lambda proxy failed: Lambda error: Failed to assume role"

Cause: Usually a configuration mismatch between the role name in admin config and the actual IAM role.

Solution: 1. Check your admin config file (~/.cognito-admin-config.json) for the correct long_lived_role_name 2. Verify the IAM role exists with exactly that name 3. Verify the Lambda's DEFAULT_ROLE_ARN environment variable matches

Testing the Setup

You can verify your setup with these AWS CLI commands:

# Test IAM user can assume the role
AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... \
aws sts assume-role \
--role-arn arn:aws:iam::ACCOUNT:role/CognitoLongLivedRole \
--role-session-name test-session

# Test Lambda function directly
aws lambda invoke \
--function-name cognito-credential-proxy \
--payload '{"id_token":"test-token","duration_seconds":7200}' \
output.json

# Check Lambda logs
aws logs tail /aws/lambda/cognito-credential-proxy --follow

AWS CLI Integration Issues

Unable to Locate Credentials

Symptoms:

$ aws s3 ls
Unable to locate credentials. You can configure credentials by running "aws configure".

Solutions:

  1. Check AWS Credentials File:
cat ~/.aws/credentials
  1. Re-login with Cognito:
cogauth login -u your-username
  1. Specify Profile:
aws s3 ls --profile default

Access Denied with AWS Commands

Symptoms:

$ aws s3 ls
An error occurred (AccessDenied) when calling the ListBuckets operation

Solutions:

  1. Check Current Identity:
aws sts get-caller-identity
  1. Verify Role Permissions:
cogadmin role info
  1. Add Required Permissions:
cogadmin policy create-s3-policy --bucket-name your-bucket

Performance Issues

Slow Authentication

Solutions:

  1. Use Local Configuration:
# Create project-specific config
cp ~/.cognito-cli-config.json ./cognito-cli-config.json
  1. Optimize Network:
  2. Use appropriate AWS region
  3. Check network connectivity
  4. Use VPC endpoints if in AWS

Frequent Re-authentication

Solutions:

  1. Use Longer Credentials:
cogauth login -u your-username --duration 12
  1. Check Credential Expiration:
aws sts get-caller-identity

Network and Connectivity Issues

Connection Timeout

Symptoms:

Error: Connection timed out

Solutions:

  1. Check Internet Connection:
ping cognito-idp.us-east-1.amazonaws.com
  1. Verify AWS Region:
export AWS_REGION=us-east-1
  1. Use Corporate Proxy:
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

SSL Certificate Errors

Solutions:

  1. Update CA Certificates:
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# CentOS/RHEL
sudo yum update ca-certificates
  1. Use System CA Bundle:
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

Advanced Troubleshooting

Enable Debug Logging

# Maximum verbosity
export BOTO_DEBUG=1
export LOG_LEVEL=DEBUG
export PYTHONPATH=/path/to/aws-cognito-auth/src

# Run with debug
python -m aws_cognito_auth.client login -u test-user

Capture Network Traffic

# Install mitmproxy
pip install mitmproxy

# Run with proxy
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080
mitmdump --mode transparent

Test Individual Components

# Test Cognito User Pool authentication
aws cognito-idp admin-initiate-auth \
    --user-pool-id us-east-1_xxxxxxxxx \
    --client-id your-client-id \
    --auth-flow ADMIN_NO_SRP_AUTH \
    --auth-parameters USERNAME=test-user,PASSWORD=test-password

# Test Identity Pool
aws cognito-identity get-id \
    --identity-pool-id "us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
    --logins cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxxxxxx=ID_TOKEN

# Test credential exchange
aws cognito-identity get-credentials-for-identity \
    --identity-id "us-east-1:12345678-1234-1234-1234-123456789012" \
    --logins cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxxxxxx=ID_TOKEN

Getting Help

Documentation

Support Channels

  • GitHub Issues: https://github.com/jiahao1553/aws-cognito-auth/issues
  • Documentation: https://jiahao1553.github.io/aws-cognito-auth/

Providing Debug Information

When reporting issues, include:

  1. System Information:
python --version
pip show aws-cognito-auth
aws --version
  1. Configuration (sanitized):
# Remove sensitive values before sharing
cat ~/.cognito-cli-config.json
  1. Error Output:
# Full command and error output
cogauth login -u test-user 2>&1
  1. Debug Logs:
# Run with debug mode
BOTO_DEBUG=1 cogauth login -u test-user > debug.log 2>&1