Move users from another identity provider or custom authentication system to Authdog with a reversible, evidence-driven plan. This guide provides a vendor-neutral inventory, export contract, identity mapping, credential strategy, staged cutover, rollback, and validation checklist.

## Prerequisites

- An Authdog [tenant, project, and environment](/docs/concepts/multi-tenancy) for staging rehearsal.
- Supported API, database, or vendor-assisted access to source users and configuration.
- An inventory of every client, backend, token validator, redirect, webhook, identity provider, and authorization dependency.
- Named owners for data mapping, security review, support, cutover, and rollback.

## Migration shape

1. **Discover** — document source behavior and downstream dependencies.
2. **Export and map** — define a versioned source-to-Authdog data contract.
3. **Rehearse and parallel run** — test production-shaped data without moving all traffic.
4. **Cut over and retire** — migrate cohorts, soak, revoke old access, and remove compatibility code.

## 1. Inventory the source

| Source concept | What to capture | Authdog target |
| --- | --- | --- |
| Users | Stable ID, identifiers, verification, profile, lifecycle state | [Users](/docs/users) |
| Credentials/factors | Password format, social links, MFA, passkeys, recovery | Authentication methods |
| Tenants/workspaces | Stable ID, names, domains, settings | [Organizations](/docs/concepts/organizations) |
| Memberships/access | User-to-org links, roles, groups, permissions | [Roles & permissions](/docs/permissions) |
| Applications/connections | Redirects, logout URLs, social and SAML/OIDC config | [Integrations](/docs/integrations) |
| Sessions/tokens | Issuer, audience, claims, lifetime, revocation | [Sessions & tokens](/docs/concepts/sessions-tokens) |
| Automation | Hooks, webhooks, provisioning, claim enrichment | Integrations, provisioning, or backend logic |

Inventory disabled/deleted users, invitations, service accounts, machine clients, email/SMS templates, rate limits, custom domains, audit retention, and every database foreign key tied to a source identity.

## 2. Define the export contract

Produce a repeatable, encrypted export containing:

- Immutable source user ID
- Email/phone/username plus primary and verification state
- Profile and required metadata
- Account status and relevant timestamps
- Provider identities and provider-side subject IDs
- Organization IDs, memberships, roles, groups, and permissions
- Credential material only when legally available and operationally required

Store the source user ID as the Authdog **external identifier**. Create explicit source organization ID → Authdog organization ID mappings. If the source lacks immutable IDs, generate a migration key once, store it in both mapping data and your application database, and never derive it from mutable email.

Version the export schema and mapping code. Record rejects with reason codes; do not silently drop malformed, duplicate, or ambiguous records.

### Password and authenticator strategy

Choose per credential cohort:

- **Compatible hash import** — only after confirming algorithm, variant, parameters, salts/peppers, encoding, and Authdog support with test vectors.
- **Progressive migration** — authenticate against the source once through a secure backend bridge, then establish an Authdog credential.
- **Reset/passwordless** — use reset, magic link, OAuth, or SSO when source verification cannot continue.
- **Re-enrollment** — plan new MFA/passkey enrollment unless both systems explicitly support secure transfer.

Never promise compatibility from hash names alone. Never export raw passwords, log credentials, or place migration secrets in client code. Encrypt exports, restrict access, audit reads, and delete artifacts after retention requirements are met.

## 3. Map organizations, roles, and identities

Create Authdog [organizations](/docs/concepts/organizations) before memberships. Distinguish global roles, organization-scoped roles, groups, entitlements, and resource-level grants. Map each to Authdog roles/permissions, metadata, or your application authorization layer; do not flatten everything into one role string.

Recreate social and enterprise SSO connections with Authdog redirect/ACS URLs. Authdog links identities by verified email, so define handling for duplicate verified emails, unverified addresses, recycled corporate addresses, missing emails, and one person with multiple source accounts.

Translate custom token claims only when consumers still need them. Prefer server-side authorization based on current organization and role state. See [Authorization](/docs/concepts/authorization).

## 4. Import and update applications

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

1. Create organizations and source-ID mappings.
2. Upsert users with profile, verification, status, and external identifier.
3. Add memberships, roles, metadata, and supported identities.
4. Quarantine ambiguous records for manual resolution.
5. Record credential migration state without exposing credential material.

Update clients using Authdog [quickstarts](/docs/quickstarts), configure the environment public key (`pk_...`), and register callbacks/logout URLs. Backends must validate Authdog sessions instead of source tokens. Update issuer-specific claims, user-ID joins, webhooks, and machine authentication. See [Backend requests](/docs/backend).

## 5. Stage cutover and rollback

1. Rehearse several complete exports/imports in staging, including rejects.
2. Take a baseline and continuously reconcile creates, profile changes, disables, memberships, and credentials.
3. Move employees, a low-risk application, or a small organization cohort first.
4. Use temporary dual-issuer validation only with explicit issuer/audience checks and metrics.
5. Stop source writes per cohort once Authdog becomes authoritative.
6. Soak, then disable source callbacks/sign-ups, revoke keys, and remove compatibility code.

Define rollback before cutover: routing switch, source write authority, maximum recovery time, data reconciliation, and criteria that trigger reversal. Test rollback with a real pilot cohort. Never assume imported credentials or sessions can be deleted safely during rollback.

## Validation checklist

- [ ] Inventory covers every application, connection, hook, and token consumer.
- [ ] User/org/membership totals and reject reports reconcile.
- [ ] Every source user has a stable external identifier.
- [ ] Password strategy passes test vectors without assumed compatibility.
- [ ] Duplicate, unverified, disabled, and multi-identity users behave correctly.
- [ ] Organizations, roles, groups, and permissions pass representative access tests.
- [ ] Social, SSO, MFA, provisioning, callbacks, logout, and webhooks pass.
- [ ] Backends validate Authdog sessions and preserve required data joins.
- [ ] Delta reconciliation, observability, support runbook, and rollback are tested.
- [ ] Source secrets and dual-issuer paths are removed after soak.

## Related

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