# Migration levers

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.

## Resolve blockers before switching

- `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](/migrate/from-workos/), [Polis shared ACS behavior](/migrate/from-polis/) and [Lever D forwarding](/migrate/from-home-grown-saml/). The plan's `source_skipped` is separate from included objects' blockers.

## Exact legacy ACS selection

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](/sso/custom-domains/) for the implemented scope.

## Keep the two cutovers separate

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](/migrate/compat-workos/) 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.
