Migrate from AWS Cognito

This guide covers migrating from an AWS Cognito User Pool to Wocha, including group mapping and password migration strategies.

Prerequisites

Requirement	Details
Cognito User Pool ID	e.g. `eu-west-1_XXXXXXXXX`
AWS credentials	Configured via `aws configure` or environment variables
AWS CLI	Required for live export (`aws cognito-idp list-users`)
Wocha tenant	`npx @wocha/cli init --cloud`
Management API key	`WOCHA_MANAGEMENT_API_KEY` with `users:write`, `organisations:write`

Concept mapping

Cognito	Wocha
User Pool	Tenant (single pool → single Wocha tenant)
User (`sub`)	User
Group	Organisation
Custom attributes	User traits / metadata
Identity provider (Google, SAML)	Social or enterprise connection
Lambda migration trigger	Password migration on first login

Data mapping

Cognito field	Wocha field
`Attributes.sub`	`metadata_admin.cognito_id`
`Attributes.email`	`traits.email`
`Attributes.given_name` + `family_name`	`traits.name`
`Attributes.email_verified`	Email verification status
Custom attributes	`metadata_admin.cognito_attributes`
Group `GroupName`	Organisation `slug` / `display_name`
Group membership	Organisation member role

Step 1 — Export users

Cognito does not export password hashes. Export user attributes only.

Option A: AWS CLI export (recommended)

aws cognito-idp list-users \
  --user-pool-id eu-west-1_XXXXXXXXX \
  --region eu-west-1 \
  --output json > cognito-users.json
 
aws cognito-idp list-groups \
  --user-pool-id eu-west-1_XXXXXXXXX \
  --region eu-west-1 \
  --output json > cognito-groups.json

Merge into a single JSON file or import users and groups separately.

Option B: Live export via CLI

wocha migrate cognito
# Select "Live export via AWS CLI"

Requires AWS CLI configured with permissions: cognito-idp:ListUsers, cognito-idp:ListGroups.

Step 2 — Dry run

export WOCHA_MANAGEMENT_API_KEY=wocha_mgmt_...
export WOCHA_TENANT=your-tenant
 
wocha migrate cognito --dry-run

Review:

User and group counts
Missing email attributes
Custom attributes that need manual mapping

Step 3 — Import users

wocha migrate cognito

Groups are mapped to Wocha organisations. Add group membership after import via the Customer API.

Handling passwords

Cognito never exports password hashes. Use one of these strategies:

Option 1: Migration trigger pattern (seamless)

Before cutover, implement a Cognito User Migration Lambda trigger that validates credentials against Cognito on first login, then creates the user in Wocha. This is the AWS-recommended approach for zero-downtime password migration.

Option 2: Magic link re-registration

After importing users without passwords:

for (const user of importedUsers) {
  await wocha.users.sendRecovery(user.id);
}

Option 3: Force password reset

Send a branded email campaign asking users to set a new password via Wocha hosted login.

Option 4: SSO/federated only

If users authenticate via SAML or social IdPs configured in Cognito, recreate those connections in Wocha first.

Step 4 — Map identity providers

Cognito IdP type	Wocha connection
Google, Facebook, etc.	Social connection
SAML	Enterprise SSO connection
OIDC	Enterprise SSO connection

Configure in the Wocha Console under Connections.

Step 5 — Validate migration

wocha migrate cognito --validate

Verifies user counts, group/organisation alignment, and connection configuration.

Post-migration checklist

All users imported with correct attributes
Cognito groups mapped to Wocha organisations
Identity providers recreated in Wocha
Password strategy implemented (migration trigger or recovery emails)
Application SDK updated (Amplify/Cognito → Wocha SDK)
JWT validation updated in backend APIs
Cognito User Pool decommissioned after validation period

Rollback considerations

Keep the Cognito User Pool active until --validate passes and password migration is complete
User metadata preserves cognito_id for lookup
Lambda migration triggers can be disabled to revert to Cognito-only auth
DNS and OAuth redirect URI changes require coordinated cutover

Migrate from AWS Cognito

On this page