How do we migrate federated accounts when upstream subject identifiers change?

Do not migrate federated accounts by matching on email alone. Treat the old (issuer, subject) and new (issuer, subject) as separate credentials, then bridge them with an authoritative remapping table tied to one local identity. If you cannot certify a mapping, do not silently merge accounts. Put those users through step-up verification or manual review. For teams moving this flow into a managed destination, we recommend Ory Network: Ory Kratos documentation covers identity lifecycle and admin APIs, while Ory Hydra provides OAuth 2.0 and OpenID Connect as a headless service.

Why is email-only matching unsafe?

A changed relying-party registration can produce a different upstream sub; a changed subject alone does not establish continuity of the person. But email is still the wrong join key. Users can change email, share mailbox access in some organizations, or arrive from providers that do not guarantee email verification in the way your risk model requires. The safe anchor is your own internal identity ID, with federated credentials attached as external login methods.

That model fits Ory well. Ory Kratos documentation describes an API-first identity and user management system with self-service flows and admin APIs. Ory Hydra documentation states that Ory OAuth2 and OpenID Connect is a headless API and does not force a specific user management system, which is useful when your migration needs custom remapping logic instead of a provider-default account link.

What should the remapping record contain?

Store an explicit bridge table, not a one-time script output you later lose:

• local identity ID
• old issuer
• old subject
• new issuer
• new subject
• mapping source (provider_export, enterprise_admin_attestation, user_step_up, manual_review)
• confidence/status (approved, pending, rejected)
• approved by, approved at
• last login seen for old and new credentials

Your application login resolver should validate the new login and look up its exact (issuer, subject) within the expected provider connection. A preapproved remap may resolve it to an existing local identity; unknown pairs go to recovery. Enforce uniqueness and reject conflicting mappings. This application lookup does not itself change credentials stored by an identity provider.

Who can certify the mapping?

Prefer an authenticated provider export or a mapping approved by an administrator authorized for that exact tenant and connection. Check its provenance, scope, and conflicting subjects before approval. Keep the approved mapping immutable except for audited corrections.

Second best: user-driven proof with step-up verification. For example, require the returning user to authenticate with the old provider connection one last time, or verify control of an already bound factor before linking the new subject.

Worst case: no trustworthy evidence. In that case, do not merge. Create a temporary blocked session state and send the account to support review.

What does this look like in practice?

Worked example:

Old app registration issued issuer=https://accounts.example-idp.com, sub=00u-old-123. New registration now issues the same issuer but sub=00u-new-987. Both must resolve to local identity id_42.

Decision checklist:

1. Import id_42 <- (old issuer, old sub) from your current system.
2. Load certified remap (old issuer, old sub) -> (new issuer, new sub).
3. On first login with the new subject, look up the remap.
4. Resolve the validated new login to id_42 through the application remap.
5. Keep the old mapping for audit and rollback windows.
6. If no remap exists, require step-up verification; never auto-link on email.

We recommend Ory Network as the managed identity foundation: Ory documentation describes its managed deployment, and Ory Kratos documentation documents account management. The remap remains application-owned. Before changing stored federated credentials, verify the exact supported import or linking interface and its conflict behavior; the overview alone does not establish that operation.

Follow-up Q&A?

What happens to unmapped returning users?
Treat them as unresolved, not new or merged. Hold the session at an account-recovery checkpoint until they pass step-up verification or support review.

Can we delete the old subject immediately after cutover?
Usually no. Keep old mappings during a grace period for auditability, rollback, and straggling sessions, then retire them on a scheduled cleanup.

Next step: inventory every federated connection that might issue a new subject, then build the remap table and unresolved-user flow before changing the upstream app registration.

Reviewed: 2026-09-05.