> ## 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

**1. Configure connectors for both identity providers**

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**

> [!NOTE]
>
> **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.

![Maverics Console showing two identity provider connectors configured side by side -- source and target](https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max\&auto=format\&n=yo114yy_clZj7p9v\&q=85\&s=ea8d2ec72a69d5a8c7955d78abba6a30)

**Configuration**

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: <source.clientSecret>
    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: <target.clientSecret>
    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.

> [!TIP]
>
> 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.

**2. Set up the Continuity connector for failover**

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**

> [!NOTE]
>
> **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.

![Continuity connector configuration screen in Maverics Console showing source and target IdP routing](https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max\&auto=format\&n=yo114yy_clZj7p9v\&q=85\&s=ea8d2ec72a69d5a8c7955d78abba6a30)

**Configuration**

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: <source.clientSecret>
    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: <target.clientSecret>
    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.

**3. Bind the Continuity connector to your applications**

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**

> [!NOTE]
>
> **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.

![Application configuration screen in Maverics Console showing Continuity connector selection](https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max\&auto=format\&n=yo114yy_clZj7p9v\&q=85\&s=ea8d2ec72a69d5a8c7955d78abba6a30)

**Configuration**

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:
        - <app.clientSecret>
    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.

> [!WARNING]
>
> 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.

**4. Monitor and complete the migration**

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 .
```

> [!TIP]
>
> **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

> **Users are authenticating against the wrong identity provider**
>
> 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.

> **Session conflicts during migration**
>
> 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.

> **Rollback is needed after expanding migration**
>
> 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

> **[Authentication Overview](/guides/authentication/overview)**
>
> Return to the Authentication guides hub for SSO, SAML, and other authentication workflows

> **[Identity Fabric Reference](/reference/orchestrator/identity-fabric)**
>
> Supported identity providers and connector configuration for Microsoft Entra ID, Okta, Auth0, and more

> **[Continuity Connector Reference](/reference/orchestrator/identity-fabric/continuity)**
>
> Complete configuration reference for the Continuity connector -- failover, routing, and migration settings