> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrate Between Identity Providers
By the end of this guide, you will have a Maverics deployment that seamlessly routes authentication between your old and new identity providers -- migrating users with zero downtime and no application changes.
## Why Migrate Identity Providers?
Identity provider migration is one of the most common -- and most stressful -- projects in enterprise IAM. Organizations outgrow their current IdP, acquire companies running different providers, consolidate after mergers, or switch to a provider with better pricing or features. Whatever the reason, the migration usually affects every user and every application in the organization.
The traditional approach is painful: reconfigure every application to trust the new IdP, migrate all user accounts, coordinate a cutover date, and hope nothing breaks. With the Maverics Orchestrator, migration becomes gradual and reversible. The Orchestrator sits between your applications and both identity providers, routing authentication to whichever IdP is appropriate for each user -- so you can migrate users in batches, roll back instantly if something goes wrong, and keep every application running throughout the process.
## Prerequisites
* **A running Maverics Orchestrator** -- If you have not installed the Orchestrator yet, follow the [Quick Start guide](/guides/getting-started/quick-start) or see the [installation reference](/reference/orchestrator/installation).
* **Source identity provider connector configured** -- Your Orchestrator should already be connected to your current (source) IdP. The [SSO with OIDC guide](/guides/authentication/sso-with-oidc) covers connector setup.
* **Target identity provider account** -- You need credentials and access to the new IdP you are migrating to (for example, moving from [ADFS](/reference/orchestrator/identity-fabric/adfs) to [Microsoft Entra ID](/reference/orchestrator/identity-fabric/azure-ad), or from [Okta](/reference/orchestrator/identity-fabric/okta) to [Auth0](/reference/orchestrator/identity-fabric/auth0)).
## Configure the Migration
The first step is connecting the Orchestrator to both your source (current) and target (new) identity providers. Each provider gets its own [Identity Fabric](/reference/orchestrator/identity-fabric) with independent credentials and configuration.
If you already have a connector configured for your source IdP (from your existing Maverics deployment), you only need to add the new target connector. The Orchestrator can maintain active connections to both providers simultaneously -- users authenticating against either provider will have a seamless experience.
**Console UI documentation is coming soon.** This section will walk you
through configuring this component using the Maverics Console's visual
interface, including step-by-step screenshots and field descriptions.
Define both connectors in the `connectors` section of your `maverics.yaml` file. Each connector has its own credentials and discovery endpoint.
```yaml maverics.yaml theme={null}
connectors:
- name: source-idp
type: oidc
oidcWellKnownURL: https://source-idp.example.com/.well-known/openid-configuration
oauthClientID: orchestrator-source-client
oauthClientSecret:
oauthLoginRedirect:
urls:
- https://your-orchestrator.example.com/oidc-callback
oauthLogoutRedirect:
urls:
- https://your-orchestrator.example.com/logout
scopes: openid profile email
- name: target-idp
type: oidc
oidcWellKnownURL: https://target-idp.example.com/.well-known/openid-configuration
oauthClientID: orchestrator-target-client
oauthClientSecret:
oauthLoginRedirect:
urls:
- https://your-orchestrator.example.com/oidc-callback
oauthLogoutRedirect:
urls:
- https://your-orchestrator.example.com/logout
scopes: openid profile email
```
Both connectors can use the same redirect URLs -- the Orchestrator routes callbacks to the correct connector based on the session state. Name your connectors clearly (e.g., `source-idp` and `target-idp`) to avoid confusion during migration.
Name your connectors clearly to distinguish between source and target -- for example, `okta-source` and `azure-ad-target`. Clear naming prevents configuration mistakes during migration when you are referencing connectors in policies.
The [Continuity connector](/reference/orchestrator/identity-fabric/continuity) is what makes zero-downtime migration possible. It acts as a smart router between your two identity providers -- directing each authentication request to the right IdP based on your migration policies.
The Continuity connector wraps both of your IdP connectors and adds failover logic. If a user has already been migrated to the new IdP, their authentication is routed there. If they have not been migrated yet, authentication goes to the source IdP. If either provider is temporarily unavailable, the Continuity connector can fail over to the other -- keeping authentication working even during provider outages.
Think of it as a load balancer for identity -- but instead of distributing traffic for performance, it routes authentication based on migration state and availability.
**Console UI documentation is coming soon.** This section will walk you
through configuring this component using the Maverics Console's visual
interface, including step-by-step screenshots and field descriptions.
Add a Continuity connector that references both IdP connectors. The `failover.idps` array lists connectors in priority order -- the first entry is tried first, and subsequent entries serve as fallbacks.
```yaml maverics.yaml theme={null}
connectors:
- name: source-idp
type: oidc
oidcWellKnownURL: https://source-idp.example.com/.well-known/openid-configuration
oauthClientID: orchestrator-source-client
oauthClientSecret:
oauthLoginRedirect:
urls:
- https://your-orchestrator.example.com/oidc-callback
oauthLogoutRedirect:
urls:
- https://your-orchestrator.example.com/logout
scopes: openid profile email
- name: target-idp
type: oidc
oidcWellKnownURL: https://target-idp.example.com/.well-known/openid-configuration
oauthClientID: orchestrator-target-client
oauthClientSecret:
oauthLoginRedirect:
urls:
- https://your-orchestrator.example.com/oidc-callback
oauthLogoutRedirect:
urls:
- https://your-orchestrator.example.com/logout
scopes: openid profile email
- name: migration-connector
type: continuity
strategy: failover
failover:
idps:
- target-idp
- source-idp
attributes:
- name: email
mapping:
target-idp: email
source-idp: email
- name: name
mapping:
target-idp: name
source-idp: name
```
The Continuity connector lists `target-idp` first so the Orchestrator tries the new provider first. If the target IdP is unavailable or the user has not been migrated, it falls back to `source-idp`.
The `attributes` section normalizes attribute names across providers. Even if both IdPs use the same attribute names, explicitly mapping them ensures consistent behavior regardless of which IdP handles the authentication.
See [Continuity Connector Reference](/reference/orchestrator/identity-fabric/continuity) for all available fields.
Update your application configurations to use the Continuity connector instead of pointing directly at a single IdP. This is the key change that enables failover -- your applications reference the Continuity connector, and the connector handles routing to the appropriate IdP.
**Console UI documentation is coming soon.** This section will walk you
through configuring this component using the Maverics Console's visual
interface, including step-by-step screenshots and field descriptions.
Update the `authentication.idps` array in your application definitions to reference the Continuity connector name instead of a specific IdP connector.
```yaml maverics.yaml theme={null}
apps:
- name: my-web-app
type: oidc
clientID: my-web-app
credentials:
secrets:
-
redirectURLs:
- https://your-app.example.com/callback
authentication:
idps:
- migration-connector
accessToken:
type: jwt
claimsMapping:
email: migration-connector.email
name: migration-connector.name
```
The `authentication.idps` now references `migration-connector` (the Continuity connector) instead of a specific IdP. The `claimsMapping` also references the Continuity connector's normalized attribute names -- not the individual IdP connectors. This ensures your application receives consistent claims regardless of which IdP authenticated the user.
Always start with a small group or low percentage and monitor before
expanding. IdP migrations affect every user's ability to log in -- a
cautious rollout lets you catch configuration issues before they impact
the entire organization.
With both connectors active and the Continuity connector routing authentication, the Orchestrator begins routing authentication according to your failover configuration. Monitor the migration to ensure users are authenticating successfully against the target IdP.
Key things to watch during migration:
* **Authentication success rates** -- Compare success rates between source and target IdPs. A drop in the target IdP's success rate may indicate configuration issues.
* **User complaints** -- Users who experience login problems are likely hitting the target IdP with misconfigured attributes or missing accounts.
* **Session behavior** -- Verify that sessions created by the target IdP work correctly with all your applications.
As confidence grows, you can adjust the Continuity connector's failover order. When all users are successfully authenticating against the new provider, remove the source connector from the `failover.idps` list. Eventually, you can remove the Continuity connector entirely and point applications directly at the target IdP.
```bash theme={null}
# Check Orchestrator health and connector status during migration
curl -s https://localhost:9443/status | jq .
```
**Success!** Your Maverics Orchestrator is seamlessly routing authentication
between both identity providers. Users are being migrated gradually with
zero downtime -- and your applications required no changes at all. When the
migration is complete, remove the Continuity connector and source IdP
configuration to clean up.
## Troubleshooting
Check your Continuity connector's `failover.idps` order to verify the routing
logic is correct. The first connector in the list is always tried first. If
a user who should be on the new IdP is still authenticating against the
source, the target IdP may be rejecting the user (causing failover to the
source). Use the Orchestrator logs to trace which connector handled a specific
authentication request -- the logs show the connector name and the failover
path that was followed. Also verify that the user's account exists in the
target IdP with the correct attributes.
If a user has an active session from the source IdP and then gets routed
to the target IdP on their next login, they may see unexpected behavior --
such as being asked to re-authenticate or losing session data. This happens
when session identifiers differ between the two providers. Configure the
Orchestrator to invalidate existing sessions when a user's IdP routing
changes, or set session timeouts short enough that users naturally cycle
through during the migration window. See the
[Sessions reference](/reference/orchestrator/sessions) for
session management options.
The Orchestrator supports instant rollback -- update your Continuity
connector's `failover.idps` order to list the source IdP first. Because the
Orchestrator re-reads configuration changes, the updated failover order takes
effect on the next authentication request. After rolling back, investigate the
issue, fix the target IdP configuration, and resume the gradual rollout by
restoring the target IdP to first position.
## Related Pages
Return to the Authentication guides hub for SSO, SAML, and other authentication workflows
Supported identity providers and connector configuration for Microsoft Entra ID, Okta, Auth0, and more
Complete configuration reference for the Continuity connector -- failover, routing, and migration settings