# Identity migration planning: accounts, access, and rollback > Plan an identity migration across accounts, credentials, sessions, OAuth/OIDC, and permissions, with explicit compatibility checks and rollback gates. Canonical URL: https://www.devobs.io/articles/identity-migration-planning/ By: Owen Park Published: 2026-10-02T15:30:57.664Z Updated: 2026-10-02T15:30:57.664Z Section: Identity Plan an identity migration as a coordinated change to accounts, credentials, sessions, application integrations, and permissions—not just a user import. Start with an inventory, verify compatibility for each type of state, and rehearse a bounded rollout with measurable acceptance criteria. Define how to reconcile changes after rollback before moving production users. ## Separate the migration into independent workstreams Give identity storage, authentication, OAuth/OIDC, and authorization separate migration decisions. Avoid assuming that replacing one requires replacing all of them in the same release. Ory’s documentation illustrates these architectural boundaries: - **Identity management:** Ory documents its Kratos-based Network identity service as providing self-service authentication and recovery, JSON Schema-based identity models, administrative account import APIs, and session management. These are relevant migration building blocks. [Ory identity documentation](https://www.ory.com/docs/network/kratos/intro) - **OAuth 2.0 and OpenID Connect (OIDC):** Ory documents its Hydra-based Network service as connected to Ory Identities by default, while offering a headless API that does not require a particular user management system. This provides a basis for evaluating provider replacement separately from identity-store replacement. [Ory OAuth/OIDC documentation](https://www.ory.com/docs/network/hydra) - **Permissions:** Ory documents Keto’s fine-grained permission relationships and inheritance through groups, roles, and hierarchies. Treat permission-model conversion as its own workstream rather than an incidental result of importing users. [Ory permissions documentation](https://www.ory.com/docs/network/keto) These documented capabilities are not evidence that a particular legacy export, credential, session, or token will transfer unchanged. Record the destination deployment model, relevant software and API versions, and configuration. Verify its migration-specific interfaces; do not substitute managed-service documentation for self-hosted documentation, or vice versa. ## Build an inventory with an owner for every decision For each item, record the current authority, export method, destination representation, compatibility status, retention requirement, and accountable owner. Use an explicit **unverified** status where evidence is missing; do not silently treat unknowns as supported. | Workstream | Inventory | Decision required before cutover | | --- | --- | --- | | Accounts | User IDs, tenants, profile fields, verification and disabled states | Mapping rules and handling of rejected records | | Credentials | Password-hash metadata, multi-factor authentication (MFA) enrollments, recovery methods, passkeys, linked providers | Supported transfer path or required user action | | Sessions | Identity-provider sessions, application sessions, browser cookies | Expiry, revocation, or reauthentication policy | | OAuth/OIDC | Clients, redirect URIs, scopes, claims, issuer configuration, signing-key trust | Integration changes and token transition policy | | Authorization | Roles, groups, ownership, resource relationships, tenant boundaries | Destination model and expected access decisions | | Operations | Writers, event consumers, support procedures, deletion workflows | Authority during transition and rollback behavior | Inspect downstream application references as well as the identity platform. Include user IDs stored in application databases, resource ownership records, audit systems, and permission relationships in the mapping review. ## Preserve account identity, not just profile fields Design a durable mapping between the legacy account identifier, destination identifier, and application-owned user record. Include the source system and tenant wherever they are needed to disambiguate identifiers. Test the mapping against explicit invariants: - Every in-scope source account has one intended outcome: migrated, deliberately excluded, or blocked for resolution. - Each destination account maps to the intended application record. - Disabled-account and verification states receive deliberate treatment. - Resource ownership and permission references resolve to the intended account. - Tenant boundaries remain intact. Do not merge accounts solely because email addresses match. Require a reviewed linking rule and evidence of control over the accounts being linked. Treat account linking as a security-sensitive operation, not a deduplication shortcut. Validate the legacy data model and linking rules independently of whether the destination can store the resulting profile fields. ## Prove credential compatibility before choosing a strategy Make credential transfer a compatibility investigation. For passwords, compare the actual hash algorithm, parameters, encoding, and any pepper dependency with the destination’s documented import support. Review MFA enrollments, recovery codes, linked-provider identifiers, and passkeys separately. Evaluate migration strategies conditionally: - **Bulk credential import:** Select it only after confirming supported formats and validating representative imports. - **First-login migration:** Consider it only if a documented, secure integration can validate the legacy credential and establish the destination credential. Specify failure handling and a retirement deadline for the legacy dependency. - **Credential reset or reenrollment:** Use it where transfer is unsupported or unsuitable, after testing recovery delivery, account-control checks, and the user journey. Do not interpret support for an authentication method as proof that existing enrollments are importable. For an Ory migration, obtain migration-specific documentation and validate representative records before committing to password-hash transfer, MFA-secret transfer, passkey transfer, or a first-login strategy. The [identity overview](https://www.ory.com/docs/network/kratos/intro) documents authentication methods and account import, but those general capabilities are not sufficient evidence for any particular transfer path. ## Plan session and token transitions separately Write a transition policy for each authentication artifact rather than promising that users will remain signed in. For identity-provider and application sessions, test cookie scope, expiration, logout, revocation, and the point at which reauthentication becomes necessary. Review access, refresh, and ID tokens separately. Check issuer and audience validation, subject mapping, signing-key trust, expiry, refresh, and revocation wherever applicable to the token type and integration. Assign each artifact a deliberate outcome supported by the systems involved: continue accepting it for a bounded period, let it expire, revoke it, or require replacement through authentication. Define the deadline and acceptance conditions for any overlap period. Validate the chosen outcome in every affected application and API. Review OAuth/OIDC clients individually, including redirect URIs, scopes, claims, client authentication, consent behavior, and subject identifiers. Include machine-to-machine clients rather than limiting tests to interactive login. For Ory, the documented [session lifecycle controls](https://www.ory.com/docs/network/kratos/intro) and [OAuth/OIDC service](https://www.ory.com/docs/network/hydra) provide starting points for this investigation—not proof of legacy session or refresh-token portability. Make continuity a separate acceptance requirement. ## Validate authorization with grants and denials Build a test set of subject–resource–action cases with reviewed expected outcomes. Cover requests expected to succeed and requests expected to be denied, including inherited access, ownership changes, disabled or deleted accounts, and cross-tenant requests. Where a relationship-based model is the destination, map both the relationships and the rules that derive access from them. Ory’s Keto documentation illustrates this distinction with stored relationships and permission rules that evaluate them. [Ory Keto permission model](https://www.ory.com/docs/network/keto) If comparing old and new decisions during rollout, designate one enforcement authority for each request scope or cohort. Use the other result for comparison until the acceptance gate is met. Investigate mismatches against the intended policy rather than assuming either implementation is automatically correct. Set security gates such as zero unintended grants and zero cross-tenant access in the required test set. Record what that set covers and which coverage gaps block rollout. Do not let a high aggregate match rate hide a case where access should have been denied. ## Rehearse concurrent changes and cohort cutover Rehearse with representative test data, including duplicates, missing fields, interrupted imports, and partial failures. Make retries safe: rerunning a batch should not create duplicate identities, lose mappings, or overwrite newer state. Decide how registrations, password changes, recovery events, account linking, deletions, and permission updates will behave during the transition. For each operation, designate the authoritative writer and define how the destination catches up. Test reconciliation explicitly; do not use matching total account counts as the sole acceptance criterion. Before expanding a cohort, require evidence for these gates: | Gate | Required evidence | | --- | --- | | Import completeness | Reconciled records with every exclusion or failure accounted for | | Identifier integrity | No unresolved collisions or dangling references in scope | | Authentication | Login, MFA, recovery, and logout pass the required scenarios | | Integration compatibility | Required clients and APIs pass their transition tests | | Authorization | Reviewed grant and denial cases pass, including tenant isolation | | Operations | Latency, error rates, and support demand remain within predeclared limits | Choose numerical operational thresholds before the rehearsal, using existing baselines and service objectives. Define who can pause the rollout and which failures require an immediate stop. Keep passwords, tokens, and credential material out of migration logs. ## Make rollback a state-reconciliation plan Do not define rollback as merely changing traffic routing. Specify what happens to state written after cutover: new registrations, credential changes, recovery events, account links, deletions, and permission updates. For each change type, document whether it can be reconciled safely, must remain on the destination, or requires a user-facing recovery action. Prevent stale snapshots from restoring revoked access or reactivating disabled accounts. Rehearse rollback after exercising these changes—not only immediately after a clean import. If a change cannot be reversed safely, identify that boundary in advance and provide a forward-recovery plan. The final go/no-go decision should answer three questions: 1. Do in-scope accounts and application references resolve to the intended principals? 2. Do the required authorization cases enforce the intended policy? 3. Can the team stop or recover without discarding security-relevant changes? Advance the migration only when reconciliation and testing support those answers. ## Source references - - -