🔐 AWS Cognito User Pool CSV Exporter

🚀 Export Amazon Cognito User Pool users to CSV format with ease!

A powerful Python script that exports user records from AWS Cognito User Pool to CSV format, perfect for user data migration, backup, or analysis.

✨ Features

• 📊 Bulk Export: Export all users or specify a maximum number
• 🔄 Pagination Support: Handles large user pools automatically
• ⚡ Fast Processing: Optimized for performance with configurable limits
• 🛡️ AWS Profile Support: Use different AWS profiles for multi-account setups
• 📝 Customizable Output: Specify custom file names and paths
• 🔧 Resume Support: Continue exports from a specific pagination token
• ✅ Import Ready: Generated CSV is optimized for Cognito User Pool imports
• 🔗 Federated Users: Export mapping and link IdP after import

🛠️ Installation

Prerequisites

• Python 3.8 or higher
• AWS CLI configured or valid AWS credentials
• Access to AWS Cognito User Pool

Quick Setup

1. Clone the repository:

   git clone https://github.com/dmytro-udovychenko/cognito-csv-exporter.git
   cd cognito-csv-exporter

2. Create and activate virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

🚀 Quick Start

Basic Usage

# Export all users from a Cognito User Pool
python3 CognitoUserToCSV.py --user-pool-id us-east-1_XXXXXXXXX

Confirm RESET_REQUIRED Users

Use this script to convert all users with status RESET_REQUIRED to CONFIRMED by setting a permanent password (required for federated sign-in to work).

# Run with AWS profile and user pool id
AWS_PROFILE=${aws_region} ./confirm-reset-required.sh us-east-1_XXXXXXXXX

Optional environment variables:

# Provide a single temporary password for all users
TEMP_PASSWORD='TempPassw0rd!Aa1' AWS_PROFILE=${aws_region} ./confirm-reset-required.sh us-east-1_XXXXXXXXX

# Dry run (do not change users)
DRY_RUN=true AWS_PROFILE=${aws_region} ./confirm-reset-required.sh us-east-1_XXXXXXXXX

With AWS Profile

# Use specific AWS profile
AWS_PROFILE=${aws_region} python3 CognitoUserToCSV.py \
  --user-pool-id us-east-1_XXXXXXXXX \
  --region ${aws_region} \
  --profile ${aws_profile}

Advanced Usage

# Export with custom settings
python3 CognitoUserToCSV.py \
  --user-pool-id us-east-1_XXXXXXXXX \
  --region ${aws_region} \
  --file-name exported_users.csv \
  --num-records 1000 \
  --profile ${aws_profile}

Export Federated Mapping (for IdP linking)

python3 CognitoUserToCSV.py \
  --region ${aws_region} \
  --file-name uid_users.csv \
  --federated-map-file federated_map.csv \
  --profile ${aws_profile}

Link Federated Users (after import)

python3 LinkFederatedUsers.py \
  --user-pool-id us-east-1_XXXXXXXXX \
  --region ${aws_region} \
  --map-file federated_map.csv \
  --conflicts-file conflicts.csv \
  --profile ${aws_profile}

📋 Command Line Arguments

Parameter	Required	Description	Default
--user-pool-id	✅	Cognito User Pool ID	-
--region	❌	AWS region	us-east-1
--profile	❌	AWS profile name	Default profile
--file-name / -f	❌	Output CSV filename	CognitoUsers.csv
--num-records	❌	Maximum records to export	0 (all)
--starting-token	❌	Resume from pagination token	-
--include-federated	❌	Add federated fields to CSV	off
--federated-map-file	❌	Write federated mapping CSV	-
--include-user-attributes	❌	Add source attributes (sub, identities) to CSV	off

📊 Output Format

The exported CSV includes the following attributes:

Field	Description
profile	User profile information
email	User email address
sub	Cognito immutable user ID (when --include-user-attributes is enabled)
identities	Raw federated identities JSON (when --include-user-attributes is enabled)
email_verified	Email verification status (always true)
given_name	First name
family_name	Last name
cognito:username	Cognito username (same as email)
cognito:mfa_enabled	MFA status
federated_provider	Primary federated provider name (e.g., Google, SignInWithApple)
federated_user_id	Provider user ID
federated_provider_type	Provider type reported by Cognito
...and more	Additional standard Cognito attributes

🧩 Import Federated Users

AWS Cognito import job does not support importing federated links via CSV. Solution: import users with the standard CSV, then link IdP accounts via API.

1. Export the import CSV and the mapping file:

python3 CognitoUserToCSV.py \
  --user-pool-id us-east-1_XXXXXXXXX \
  --region ${aws_region} \
  --file-name import_users.csv \
  --federated-map-file federated_map.csv \
  --profile ${aws_profile}

2. Import import_users.csv into Cognito.

3. Link IdP accounts (conflicts are written to conflicts.csv):

python3 LinkFederatedUsers.py \
  --user-pool-id us-east-1_XXXXXXXXX \
  --region ${aws_region} \
  --map-file federated_map.csv \
  --conflicts-file conflicts.csv \
  --profile ${aws_profile}

Note: federated_* fields are added to the export only with --include-federated. For Cognito import, use the CSV without these fields.

🔧 Special Features

• Email Verification: All exported users have email_verified set to true for seamless imports
• Username Mapping: cognito:username is automatically mapped to the user's email
• MFA Detection: Automatically detects and exports MFA status

💡 Examples

Export Specific Number of Users

python3 CognitoUserToCSV.py \
  --user-pool-id us-east-1_XXXXXXXXX \
  --region ${aws_region} \
  --num-records 500 \
  --file-name first_500_users.csv \
  --profile ${aws_profile}

Export User Attributes (sub, identities, email)

python3 CognitoUserToCSV.py \
  --user-pool-id us-east-1_XXXXXXXXX \
  --region ${aws_region} \
  --include-user-attributes \
  --file-name users_with_attributes.csv \
  --profile ${aws_profile}

Resume from Previous Export

python3 CognitoUserToCSV.py \
  --user-pool-id us-east-1_XXXXXXXXX \
  --region ${aws_region} \
  --starting-token "your-pagination-token" \
  --file-name continued_export.csv \
  --profile ${aws_profile}

Multi-Region Export

# Export from different regions
python3 CognitoUserToCSV.py \
  --user-pool-id us-east-1_XXXXXXXXX \
  --region ${aws_region} \
  --file-name eu_users.csv \
  --profile ${aws_profile}

🔍 Troubleshooting

Common Issues

Permission Denied:

# Ensure your AWS credentials have the required permissions:
# - cognito-idp:ListUsers
# - cognito-idp:DescribeUserPool

Module Not Found:

# Make sure you're in the virtual environment
source venv/bin/activate
pip install -r requirements.txt

SSL Certificate Errors:

# Update certificates
pip install --upgrade certifi

📞 Getting Help

If you encounter issues:

1. Check your AWS credentials and permissions
2. Verify the User Pool ID is correct
3. Ensure you have network connectivity to AWS
4. Review the error message for specific details

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Test thoroughly
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Original project by hawkerfun
• AWS Cognito documentation and community

📚 Related Tools

For complete Cognito backup and restore operations, consider:

• cognito-backup-restore - Full backup solution

---

Made with ❤️ for the AWS community

Report Bug · Request Feature · Documentation