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.

Console terminology: In the Maverics Console, the combination of applications, policies, headers, and connector bindings is managed through User Flows. In YAML, these elements are configured directly within each app’s configuration block under apps[].policies[].

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 or see the installation reference.
Source identity provider connector configured — Your Orchestrator should already be connected to your current (source) IdP. The SSO with OIDC guide 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 to Azure AD, or from Okta to Auth0).

Configure the Migration

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

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

Define both connectors in the connectors section of your maverics.yaml file. Each connector has its own credentials and discovery endpoint.

maverics.yaml

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.

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.

Set up the Continuity connector for failover

The Continuity connector 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
Configuration

Continuity connector configuration screen in Maverics Console showing source and target IdP routing

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.

maverics.yaml

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 for all available fields.

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
Configuration

Application configuration screen in Maverics Console showing Continuity connector selection

Update the authentication.idps array in your application definitions to reference the Continuity connector name instead of a specific IdP connector.

maverics.yaml

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.

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.

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.

# 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

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

Authentication Overview

Return to the Authentication guides hub for SSO, SAML, and other authentication workflows

Identity Fabric Reference

Supported identity providers and connector configuration for Azure AD, Okta, Auth0, and more

Continuity Connector Reference

Complete configuration reference for the Continuity connector — failover, routing, and migration settings

Getting Started

Authentication

AI Identity

Operations

Security

Why Migrate Identity Providers?

Prerequisites

Configure the Migration

Troubleshooting

Authentication Overview

Identity Fabric Reference

Continuity Connector Reference

Getting Started

Authentication

AI Identity

Operations

Security

​Why Migrate Identity Providers?

​Prerequisites

​Configure the Migration

​Troubleshooting

​Related Pages

Authentication Overview

Identity Fabric Reference

Continuity Connector Reference

Why Migrate Identity Providers?

Prerequisites

Configure the Migration

Troubleshooting

Related Pages