Identity Migration

Scope

Moving identity providers is usually where hidden complexity becomes visible. This public guide keeps the planning, risk, and cutover guidance from the deeper manual without exposing private migration interfaces or implementation mechanics.

Access

Requirements:

• active tenant context
• portal.migrations.view to inspect workspaces and sources
• portal.migrations.manage to create workspaces, sources, cutover plans, previews, applies, OCM acknowledgements, and post-cutover evidence updates

Scope rules:

• operator-tenant sessions may manage migration workspaces across customer tenants
• customer or vendor tenant sessions may only access their own tenant path
• guest_access and support_access contexts are denied because migration state requires membership-backed tenant context

Current Shipped Scope

• one durable migration workspace per tenant
• two workspace modes:
• first_run_adoption
• merge_into_existing
• durable source-connection records for Okta and Entra
• encrypted-at-rest source secret storage
• audit records for workspace and source creation
• read-only inventory collection for one configured source at a time
• durable inventory snapshots, normalized inventory items, and page-level raw evidence metadata
• snapshot list, latest, and detail read routes
• durable assessment runs bound to one completed inventory snapshot
• durable per-item compatibility classifications for the shipped M2 inventory item set
• durable bounded OCM and unavoidable-change impact rows where the classifier can support them honestly
• durable merge-decision rows for truthfully detected live-tenant overlaps in merge_into_existing
• assessment list, latest, and detail read routes
• merge-decision list and resolve routes
• OCM acknowledgement routes
• preview-handoff readiness state derived from merge and OCM review completion
• durable cutover-plan rollback guidance and post-cutover completion evidence
• cutover-plan create, list, detail, preview, and apply routes
• cutover-evidence read and update routes
• preview-token-protected apply for the bounded first_run_adoption and merge_into_existing contracts
• truthful execution readback for created, blocked, skipped, manual-follow-up, and failed steps
• operator-facing post-cutover handoff criteria, rollback notes, and communications evidence in the Portal workspace
• one dedicated Portal route and nav entry for migration tooling under Configuration -> Migration Tooling

Current shipped cutover automation remains intentionally bounded:

• only workspaces whose latest assessment handoff is already ready_for_future_preview may create, preview, or apply cutover plans
• merge mode consumes explicit persisted merge decisions and never silently overwrites the matched Portal runtime row
• apply only creates the supportable targets described below

Use The Portal UI

Operators can now use the first tenant-scoped Portal workspace for migration tooling:

• open Configuration -> Migration Tooling
• the page loads the first workspace for the active tenant plus its sources, latest snapshot, latest assessment, and any existing cutover plan bound to that assessment
• the workspace exposes the current preview-handoff gate, OCM acknowledgement action, plan summary counts, step-level dispositions, preview state, apply-only outputs, and post-cutover evidence or handoff notes

The UI does not yet expose workspace or source creation. Those setup steps still use the backend routes directly.

Create A Workspace

Create the tenant workspace:

Request body:

Rules:

• each tenant can have only one active workspace in this slice
• new workspaces start in draft

List or read the workspace:

Add A Source Connection

Create a source under the workspace:

Current supported contracts:

Okta

Entra

Rules:

• Okta currently supports only connection_mode=api_token
• source names must be unique within one workspace
• archived workspaces cannot accept new sources

List or read sources:

Secret Handling

Portal stores source credentials encrypted at rest and never returns raw secret material in list or detail responses.

Responses expose only:

• connection metadata
• source status

Portal now uses these secrets only for read-only inventory collection against the configured source. The inventory slice does not mutate Portal runtime or the incumbent platform.

Operational note:

• the configured Okta token must be able to read applications, groups, identity providers, routing rules, policies, domains, and assignment targets
• the configured Entra application must be able to read applications, service principals, domains, groups, conditional-access policies, and app-role assignments

Collect An Inventory Snapshot

Trigger a source snapshot:

Current read-only source domains:

Okta

Entra

• application registrations from Microsoft Graph the relevant workflow
• service principals from Microsoft Graph the relevant workflow
• verified domains from Microsoft Graph the relevant workflow
• groups from Microsoft Graph the relevant workflow
• conditional-access policies from Microsoft Graph the relevant workflow
• service-principal app-role assignments from Microsoft Graph the relevant workflow

Current response shape includes:

• snapshot status and timestamps
• source-type summary counts
• normalized inventory items across applications, providers, routing rules, policies, groups, assignments, and domains
• raw-evidence metadata for each collected endpoint page

Read back snapshots:

Important contract notes:

• collection is synchronous and read-only in this slice
• only one collection run may be active per source at a time
• archived workspaces and non-configured sources cannot collect inventory
• snapshot detail exposes normalized items plus per-item raw payloads and evidence metadata, but it does not yet expose a dedicated raw-evidence download route

Run A Compatibility Assessment

Trigger a snapshot-scoped assessment:

Read back assessment history:

Assessment runs are durable and rerunnable for the same completed inventory snapshot. Portal keeps historical runs instead of overwriting the prior result.

Current compatibility classes:

• native_import
• import_with_approximation
• visibility_only
• manual_rebuild_required
• blocked

Current assessment response detail includes:

• assessment status and timestamps
• classifier version
• per-item target contract, rationale, approximation notes, blocked reason, and operator or user impact levels
• bounded OCM impact rows with audience, severity, summary, and related item references
• merge-decision rows for assessment items that truthfully collide with live tenant state in merge mode

Additional review routes now exist for completed assessment runs:

Important contract notes:

• assessment is read-only in this slice and does not mutate live Portal runtime
• only completed inventory snapshots may be assessed
• archived workspaces and non-configured sources cannot run assessment
• only one assessing run may be active per snapshot at a time
• direct-user assignment rows stay blocked until later identity-link and merge-decision work exists
• merge-decision review only applies to merge_into_existing workspaces
• map_to_existing resolution must point at one of the persisted matched_resources for that assessment run
• OCM acknowledgement updates the existing persisted impact rows; it does not create a second acknowledgement object

Work With A First-Run Cutover Plan

Current cutover-plan routes:

Create request body:

Current rules:

• cutover plans are bound to one workspace, one source, one inventory snapshot, and one completed assessment run
• both first_run_adoption and merge_into_existing workspaces are eligible in this tranche
• the referenced assessment must already be completed
• the assessment handoff must already be ready_for_future_preview
• unacknowledged OCM impacts or other live handoff blockers still reject create, preview, and apply
• apply requires the current matching preview_token from the latest preview response

Current supportable auto-create contracts:

• upstream SAML providers when evidence includes the entity ID, SSO URL, and signing certificate Portal needs for truthful creation
• simple domain-based federation routing rules that depend on a provider created in the same execution run or explicitly mapped to an existing provider through merge review
• tenant-scoped groups
• tenant-owned custom OIDC applications recreated from compatible Okta OIDC application evidence or compatible Entra application-registration evidence
• group-targeted tenant app assignments when the referenced tenant app and group both resolve through same-plan create or explicit merge mapping

Current supportable merge-mode bindings:

• map_to_existing for overlapped upstream providers, routing rules, tenant-owned applications, and tenant-scoped groups
• net-new safe creates for supportable contracts when no live overlap exists
• group-targeted tenant app assignment creation when the app and group dependencies resolve through same-plan create or map_to_existing

Current non-auto-created outcomes:

• direct-user app assignments remain blocked
• Entra OIDC-style service principals remain manual_follow_up because the collected evidence does not yet distinguish whether Portal should create a confidential or public client
• auth-policy approximation rows remain manual_follow_up because the current cutover lane does not collapse per-rule approximation into one tenant-wide auth-policy mutation automatically
• overlap-driven create_new decisions stay explicit follow-up when the persisted merge-review state does not carry enough rename or alternate target-shape data to avoid the captured collision safely
• generated OIDC client secrets are returned only once in the apply response and are not stored as durable readback

Work With Post-Cutover Evidence

Current evidence routes:

Current evidence response includes:

• the current cutover plan detail
• the latest execution run when apply has been attempted
• durable rollback guidance stored on the cutover plan
• durable post-cutover completion evidence stored on the cutover plan
• computed handoff criteria derived from the current plan and execution record

Current operator-entered rollback fields:

• rollback summary
• rollback owner
• rollback steps

Current operator-entered completion evidence fields:

• communications-complete flag
• communications summary
• artifact or ticket reference
• manual validation summary
• follow-up-reviewed flag
• follow-up summary

Current handoff criteria are truthful to the bounded cutover contract:

• Portal checks whether an execution record exists
• Portal checks whether rollback guidance is recorded
• Portal checks whether communications completion evidence is recorded
• Portal checks whether outstanding follow-up has been reviewed
• Portal does not pretend blocked or manual-follow-up rows disappeared; it only makes them explicit

Current important limits:

• Portal does not execute rollback automatically in this slice
• Portal does not run automated post-cutover provider sign-in probes or downstream app launch probes in this slice
• manual validation notes are operator-entered evidence, not machine-collected health checks

Status Behavior

Workspace lifecycle in the shipped slice:

• draft when created with no active sources
• ready_for_inventory once at least one non-archived source exists
• archived reserved for later lifecycle work

Source lifecycle in the shipped slice:

• configured
• archived

Inventory snapshot lifecycle in M2:

• collecting while the source read is in flight
• completed after the snapshot, items, and evidence rows are persisted
• failed when the external source rejects the request or returns unusable data

Assessment lifecycle in shipped M3:

• assessing while the classifier is evaluating one completed snapshot
• completed after item assessments, OCM impacts, merge decisions, and readiness summary state are persisted
• failed when the classifier cannot finish or the persistence step cannot complete cleanly

Cutover-plan lifecycle in shipped M4:

• draft after plan creation or rebuild
• previewed after a successful preview response mints the current preview token
• applied when every planned step mutates successfully
• applied_with_follow_up when the execution succeeds for supportable targets but still includes blocked, skipped, or manual-follow-up steps
• failed when a planned mutation step fails during execution

Cutover-step lifecycle in shipped M4:

• planned
• manual_follow_up
• blocked
• skipped
• applied
• failed

Execution-run lifecycle in shipped M4:

• started
• completed
• completed_with_follow_up
• failed

On successful collection, Portal updates migration_sources.last_inventory_at.

Workspace summary currently tracks:

• source_count
• configured_source_count
• ocm_status
• ocm_review_status
• unavoidable_change_count
• assessment_status
• latest_assessment_started_at
• latest_assessment_completed_at
• merge_review_status
• pending_merge_decision_count
• resolved_merge_decision_count
• preview_handoff_status
• preview_handoff_blockers

Audit

Portal emits audit records for state-changing actions:

• migration.workspace.created
• migration.source.created
• migration.inventory.collected
• migration.inventory.collection_failed
• migration.assessment.completed
• migration.assessment.failed
• migration.merge_decision.resolved
• migration.ocm_impacts.acknowledged
• migration.cutover_plan.created
• migration.cutover_plan.previewed
• migration.cutover_plan.applied
• migration.cutover_evidence.updated
• migration.cutover_step.applied
• migration.cutover_step.blocked
• migration.cutover_step.failed
• migration.cutover_step.manual_follow_up
• migration.cutover_step.skipped

Audit details include the tenant, actor, target resource id, and the non-secret configuration facts relevant to the write.

Not Yet Shipped

Do not treat the shipped M4 plus bounded M5 lanes as full migration completion. Portal still does not provide:

• full first-run automation for every assessed item type
• field-by-field overwrite or deep reconcile of existing upstream providers, routing rules, groups, or tenant-owned applications during merge mode
• direct-user assignment import
• automated rollback execution
• automated post-cutover provider or downstream application validation probes
• one-click migration claims across the full incumbent estate