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](/docs/concepts/multi-tenancy) 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

1. **Inventory and export** — capture pool configuration, users, groups, providers, and triggers.
2. **Map and import** — preserve Cognito IDs and translate attributes and access rules.
3. **Parallel run** — validate Authdog while Cognito remains available.
4. **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](/docs/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](/docs/permissions) |
| Identity providers | Social and SAML/OIDC settings, attribute mapping | [Integrations](/docs/integrations) |
| Lambda triggers | Claim enrichment, validation, messages, migration trigger | [Custom flows](/docs/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 `sub` as 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](/docs/concepts/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](/docs/users).

## 4. Import and update applications

Import through console tooling or the REST [Directory API](/docs/api):

1. Upsert profile and verification state.
2. Set Cognito `sub` as external identifier.
3. Attach required metadata and suspend disabled users.
4. Assign mapped organizations and roles.
5. Record password migration state without storing credentials.

Then replace Cognito Hosted UI/SDK entry points with Authdog ([quickstarts](/docs/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](/docs/concepts/sessions-tokens) and [Backend requests](/docs/backend).

## 5. Stage cutover and rollback

1. Rehearse full export, import, sign-in, role checks, and account linking in staging.
2. Freeze configuration changes or continuously reconcile deltas.
3. Move internal users, then one app or user cohort at a time.
4. Temporarily accept either issuer only in an instrumented compatibility layer.
5. Monitor failures, duplicate users, progressive migrations, and authorization mismatches.
6. 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 `sub` is 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.

## Related

- [Users](/docs/users)
- [Organizations](/docs/concepts/organizations)
- [Roles & permissions](/docs/permissions)
- [Authentication](/docs/authentication)
- [Deployments](/docs/deployments)