Move Amazon Cognito User Pools to Authdog while preserving Cognito sub values, application data joins, and sign-in continuity. This guide covers user export, attributes and groups, password constraints, federated identities, staged cutover, and rollback.
Prerequisites
- An Authdog tenant, project, and environment for rehearsal (staging first).
- AWS access to describe the user pool, list users and groups, inspect app clients, identity providers, Lambda triggers, and hosted UI settings.
- An inventory of every app, API, authorizer, and job that issues or validates Cognito tokens.
- Agreed cutover and rollback criteria.
Migration shape
- Inventory and export — capture pool configuration, users, groups, providers, and triggers.
- Map and import — preserve Cognito IDs and translate attributes and access rules.
- Parallel run — validate Authdog while Cognito remains available.
- Cut over and retire — move cohorts, soak, then revoke Cognito dependencies.
1. Inventory Cognito
| Cognito resource | What to capture | Authdog target |
|---|---|---|
| User pool users | sub, username, email, phone, status, attributes |
Users |
| App clients | Callback/logout URLs, OAuth flows, scopes, token lifetime | App configuration and sessions |
| Groups | Group names, precedence, IAM role mapping, memberships | Roles & permissions |
| Identity providers | Social and SAML/OIDC settings, attribute mapping | Integrations |
| Lambda triggers | Claim enrichment, validation, messages, migration trigger | Custom flows or backend logic |
| Custom attributes | Schema, mutability, required state, application usage | User metadata |
Also record MFA policy, password policy, verified aliases, case sensitivity, custom domains, email/SMS delivery, and every API that trusts the pool issuer or JWKS.
2. Export users
Use ListUsers with pagination and AdminListGroupsForUser, or an equivalent controlled export. Retain:
- Cognito
subas the stable source identifier Username, email, phone, and verification flags- Standard and
custom:*attributes - Enabled state and
UserStatus - Group memberships
- Creation and modification timestamps
- Federated provider link information when available
Store Cognito sub as the Authdog external identifier. Do not substitute email or mutable Cognito username for this mapping. Preserve a separate mapping table if downstream systems need both source and Authdog IDs.
Password strategy
Cognito does not provide password hashes through normal user export APIs. Choose and test one path:
- Progressive migration — authenticate an unmigrated user against Cognito once, then establish an Authdog credential through a secure server-side flow.
- Cognito migration trigger bridge — use Cognito's migration mechanisms only if your transition architecture specifically requires Cognito to call the bridge; validate behavior and eventual removal.
- Reset or passwordless — send a controlled reset or move users to magic link/social sign-in.
Do not claim direct hash compatibility without an Authdog-supported export format and a successful rehearsal. Never log raw passwords or send them through browser-side migration code.
3. Map attributes, groups, and identities
Map custom:* attributes individually: profile data to profile/metadata, authorization data to roles, and customer tenancy to organizations. Translate Cognito groups to Authdog roles only after reviewing group precedence and any IAM-role side effects.
For B2B pools, create organizations first, retain a cognito_tenant_id → Authdog organization mapping, then import memberships and org-scoped roles. Recreate social and enterprise providers with Authdog callback URLs. Verified-email linking can combine identities; test unverified and alias-based accounts separately. See Users.
4. Import and update applications
Import through console tooling or the REST Directory API:
- Upsert profile and verification state.
- Set Cognito
subas external identifier. - Attach required metadata and suspend disabled users.
- Assign mapped organizations and roles.
- Record password migration state without storing credentials.
Then replace Cognito Hosted UI/SDK entry points with Authdog (quickstarts), configure the environment public key (pk_...), and validate Authdog sessions on backends instead of Cognito tokens. Update code that reads cognito:groups, custom:*, username, or issuer-specific claims. See Sessions & tokens and Backend requests.
5. Stage cutover and rollback
- Rehearse full export, import, sign-in, role checks, and account linking in staging.
- Freeze configuration changes or continuously reconcile deltas.
- Move internal users, then one app or user cohort at a time.
- Temporarily accept either issuer only in an instrumented compatibility layer.
- Monitor failures, duplicate users, progressive migrations, and authorization mismatches.
- After soak, disable Cognito sign-ups and callbacks, revoke app secrets, and remove old token validation.
Rollback: route affected cohorts back to Cognito and keep source records authoritative until repaired. Do not write conflicting profile, role, or password state in both systems without a defined reconciliation rule.
Validation checklist
- User totals and disabled states match expected export deltas.
- Every Cognito
subis retained as a stable external identifier. - Password reset or progressive migration succeeds; no assumed hash compatibility.
- Attributes, groups, organizations, and roles match approved mappings.
- Social, SAML/OIDC, MFA, callback, and logout flows pass.
- APIs validate Authdog sessions and required claims.
- Delta users created during migration are reconciled.
- Rollback routing is tested before production cutover.
- Cognito app credentials and old issuer support are removed after soak.