Skip to content
Dashboard
Theme
Theme

Migration levers

The options for keeping existing IdP configurations working during a migration, and when to choose each.

View Markdown

The plan selects A, B or C per organization from included connections. Lever D is configured explicitly; the planner never selects it automatically.

  • A: retain legacy URLs. A legacy ACS uses a customer-owned host. Preserve the path and SP entity ID; arrange hostname, TLS and DNS separately.
  • B: update IdP fields. URLs belong to the old vendor. Give the IT admin new ACS, entity ID or SCIM settings through the portal.
  • C: replace key-bound settings. Assertions are encrypted or AuthnRequests need the old SP signing key. Update IdP certificates/settings and test again.
  • D: forward an app callback. Your app owns the existing ACS or OIDC callback. Register a bounded forwarding window and forward from your server.

Lever C takes priority when any included connection is bound to old SP keys, including WantAuthnRequestsSigned in metadata. Otherwise an eligible customer-owned ACS gives A; the remaining plan uses B. Retaining a URL cannot transfer a private key you do not possess.

  • idp_metadata_required: supply trusted IdP metadata through the migration portal.
  • idp_metadata_invalid, idp_metadata_fetch_failed, idp_certificate_expired: correct metadata or certificates and retry the supported configuration flow.
  • signed_authn_requests_bound_to_old_sp_key, assertion_encryption_bound_to_old_sp_key: use Lever C.
  • oidc_client_secret_required: re-enter the IdP-issued client secret securely.
  • scim_token_reissue_required: hand the new directory token to the IT admin through the migration portal.
  • acs_alias_taken, acs_alias_issuer_taken, external_id_taken: resolve the conflicting identity or alias; do not silently merge organizations.

Imported directory tokens are newly issued. Users remain out of domain until ownership is verified. Re-evaluation after verification avoids a duplicate created-event storm.

Read WorkOS metadata steps, Polis shared ACS behavior and Lever D forwarding. The plan’s source_skipped is separate from included objects’ blockers.

For Lever A, copy the actual ACS URL and SP entity ID from the old provider. In a normalized bundle, preferred_acs_url must be an exact member of legacy_acs_urls and requires the explicit legacy entity ID. Core selects a ready registered broker-host binding before starting the flow and binds the callback to it. Keeping a hostname or path alone does not satisfy that binding. See custom domains for the implemented scope.

An IdP cutover changes where assertions or authorization responses arrive. An application cutover changes which authorize, token and profile interfaces your server uses. Lever A can preserve IdP settings while the application moves to native OhAuthCat; the WorkOS SSO bridge can temporarily preserve an application contract while the IdP follows Lever B or C.

Before switching, record the selected lever, unresolved blockers, exact host/path and entity ID, test result and rollback route for each organization. A planned lever is not evidence of DNS provisioning, a transferred private key or a passing sign-in.