Identity Migration

Scope

How to move from Okta, Entra ID, a SCIM 2.0 source or a CSV export into Portal: collect an inventory, assess compatibility, plan and apply the cutover, and roll back if needed.

What it does

Migration tooling moves people, groups, applications and sign-in settings from another identity system into Portal. It works in stages, and each stage is read-only until you choose to apply:

1. Connect a source: Okta, Microsoft Entra ID, any SCIM 2.0 directory, or a CSV file.

2. Collect an inventory: Portal reads the source and stores a snapshot of what it found.

3. Assess: Portal classifies each object by how well it can be brought over and tells you what people will notice.

4. Review: acknowledge the changes people will see and, when Portal already has data, decide how overlapping objects merge.

5. Preview and apply: Portal shows exactly what it will create, then creates it in the background.

6. Record the handoff: capture rollback notes, communications and any follow-up so the migration has a clean close.

Nothing in the source system is ever changed. Portal only reads from it.

Who can use it

• View migrations lets you open the workspace and read every stage.

• Manage migrations lets you create the workspace, add sources, run inventory and assessment, acknowledge impacts, and preview and apply plans. The built-in Admin role has both.

• Turning migration capabilities on or off (below) is a tenant setting. A tenant super user changes it.

You must be signed in with a second factor and working inside your own tenant. Guest access and support-access sessions cannot open migration tooling.

Open the workspace

Open Configuration, then Migration Tooling. The page shows one workspace for your tenant with its sources, the latest inventory and assessment, the cutover plan, and the evidence panel. While the workspace is loading, Portal reserves the space, so an empty panel always means there is nothing there yet.

Create the workspace

The first visit shows Get started with migration tooling.

1. Select Create migration workspace.
2. Enter a name, for example “Q2 Okta migration”.
3. Choose the mode: - First run: your Portal tenant is empty. Portal creates everything the plan supports.

• Merge: your Portal tenant already has users, groups or applications. Portal detects overlaps and asks you to decide each one before it creates anything.

4. Select Create workspace.

Each tenant has one workspace.

Turn on the capabilities you need

Migration capabilities are switches on your tenant. They are off until a tenant super user turns them on, and they are shown at the top of the migration page under Identity Migration Capabilities. Tenant Settings links there too.

Capability	What it allows
Okta user inventory	Reads Okta users and their group memberships
Okta factor inventory	Reads which MFA factors each Okta user has
Entra user inventory	Reads Entra users and their group memberships
Entra authentication-method inventory	Reads which sign-in methods each Entra user has
Generic SCIM inventory	Allows a SCIM 2.0 source to collect at all
CSV inventory	Allows a CSV source to collect at all
Imported password-hash login	Lets people sign in with a password hash imported from Okta
MFA factor secret import	Lets Portal carry over supported authenticator secrets so people keep their existing codes

• For an inventory capability, flip the switch. It saves at once and applies only to your tenant.

• For the two secret-import capabilities, a confirmation opens. Type the capability’s name exactly as shown, write why your tenant needs it, then select Turn on. The reason is recorded in the audit log. Turning off needs no reason.

• Reset to default removes your choice so the capability follows the platform default again. The table shows both values.

Turn on the user inventory for your source before any real cutover. Without it, migrated people arrive in no groups, so any access that depends on group membership will be missing.

A source can be added while its capability is off, so you can stage a migration. Collecting from a source whose main capability is off fails and says which capability to turn on. A missing enrichment capability (users, memberships, factors) does not fail the collection; the snapshot carries a warning instead.

Importing password hashes does not weaken anything: an imported hash still has to pass validation, and the normal sign-in limits apply.

Add a source

Under Add source, the wizard has three steps: source type, credentials, review.

Source	What you provide	What the credential must be allowed to read
Okta	Okta base URL and an API token	Applications, groups, identity providers, routing rules, sign-on policies, domains, assignments; users and factors if those capabilities are on
Microsoft Entra ID	Entra tenant ID, application (client) ID and client secret	Applications, service principals, domains, groups, conditional-access policies, app-role assignments; users and authentication methods if those capabilities are on
Generic SCIM 2.0	SCIM base URL, bearer token, optional SCIM filter	Users and groups
CSV upload	The file and a column mapping	The file itself

For a CSV, Portal reads the header row and asks you to map columns to Email (required), display name, first and last name, department, title, manager email and external ID. The file uploads as soon as the source is created.

Give each source a unique name. Credentials are stored encrypted and are never shown again; the source only shows that a credential is present.

For Okta you can also choose to import password hashes and authenticator secrets. Both need the matching capability on, and the Okta token must be allowed to read that material.

Collect an inventory

Select Run inventory on the source. Collection runs in the background; the page polls until it completes or fails, and you can leave and come back. Only one collection runs per source at a time.

When it completes, the Inventory Snapshot panel shows counts by domain (applications, groups, policies, users and so on), the number of source records read, and any collection warnings. The item table is paged; choose 10, 25, 50 or 100 rows per page and the choice is remembered in your browser.

If collection fails, the snapshot says why: usually a rejected credential, a capability that is off, or unusable data from the source. Fix the cause and run it again. A collection interrupted by a restart is marked failed after an hour and can be re-run.

Run the assessment

Select Run assessment on a completed snapshot. It also runs in the background. Portal keeps every assessment, so re-running never loses an earlier result.

The Assessment items table classifies each object:

Class	Meaning
Native import	Portal creates an equivalent object
Import with approximation	Portal creates it, with a noted difference
Visibility only	Portal records it for your review but does not create it
Manual rebuild required	You recreate it in Portal by hand
Blocked	Portal will not create it; the reason is shown

Each row also shows the target Portal object, the reasoning, and the impact on people and on administrators.

The Assessment Gate panel lists what people will notice (“organisational change” impacts) and, in merge mode, each overlap between the source and your existing Portal data.

• Select Acknowledge Current OCM Impacts once you have read them and planned your communications.

• In merge mode, resolve every overlap: map the source object to an existing Portal object, or create it as new. Portal never overwrites the existing object.

The gate shows Ready for handoff when impacts are acknowledged and every overlap is decided. Until then the plan actions stay disabled and the panel lists the blockers.

If an assessment fails, the failure detail is shown in the gate panel. Fix the cause and run it again; nothing needs to be acknowledged first.

Build, preview and apply the cutover plan

1. Select Create First-Run Cutover Plan or Create Merge Cutover Plan. The plan is bound to the assessment you just completed.

2. Read the step table. Each step names the target, its status (planned, mapped, manual, blocked or skipped) and the reason.

3. Select Generate Preview Token. The preview is a snapshot of what the apply will do and is valid for a short time. If anything in your tenant changes after the preview, the apply is refused and you preview again.

4. Select Apply Previewed Plan. The apply runs in the background and the Migration apply progress panel shows steps processed, errors by cause, and an estimate of the time remaining.

Check two things before you apply

Are group memberships being migrated? Look for group-membership steps in the plan. A step marked as a manual membership dependency means the group or the person is not part of this plan, usually because the group already exists under a different identity or the person is missing from the snapshot. Those people will land in no group and lose any group-based application access. Fix the plan first. A membership that already exists in Portal shows as skipped; that is correct on a re-plan.

How will each person sign in? Every user step says how the person’s credentials are set up:

• Imported password hash: the person keeps their existing password. This happens only for Okta sources with password import on and a hash present in the export.

• Invitation email required: Portal emails the person a link to set a Portal password. This is the normal case. Okta does not expose password hashes on user reads and Entra cloud-only accounts cannot export them.

Because invitations are the normal case, confirm that email delivery is configured for your tenant before you apply. If it is not, the apply result reports the invitations as logged only, which means nobody received a link. Re-send from the user’s page for anyone not reported as sent. Plan your cutover communications around a “set your password” email on cutover day.

What the plan creates

• Upstream SAML identity providers, when the evidence includes the entity ID, sign-in URL and signing certificate. Each is created disabled, then tested. If the test passes and the plan asked for it, the connection is enabled. If it fails, the connection stays disabled with the reason, and the step asks you to fix, test and enable it from Identity providers. A cutover never produces an enabled connection that was never tested.

• Domain-based routing rules that point at a provider created in the same run or mapped through merge review.

• Groups.

• OIDC applications recreated from compatible Okta OIDC applications or Entra application registrations.

• Group-based application assignments where both the application and the group resolve in the same plan.

What stays manual

• Direct user-to-application assignments.

• Entra service principals, because the evidence does not say whether the client should be confidential or public.

• Sign-in policy approximations.

• Merge decisions to create a new object where the collision cannot be avoided safely.

These stay in the plan as manual follow-up, blocked or skipped so nothing is guessed into your tenant.

Generated application secrets

If the run created OIDC applications, their client secrets are shown once under Apply-Only Outputs after the run finishes. Copy them straight away. Portal cannot show them again, and unrevealed secrets are destroyed after 24 hours. If you missed the window, rotate or recreate the client.

Follow the apply

The progress panel shows the run status:

Status	Meaning
Queued	Accepted and waiting to start
In progress	Steps are being applied
Cancellation requested	Portal will stop at the next safe step
Succeeded	Every step applied
Completed with follow-up	Some steps applied; some failed or need follow-up
Failed	No step applied
Cancelled	Stopped before finishing

Cancel Apply stops future steps. It does not undo steps already applied: imported users, generated clients and secrets, created providers and rules, and created groups remain in place. Give a reason; it is recorded.

Download error CSV lists every failed step with its cause.

Recover from a cancelled or partly successful apply

1. Open the Evidence panel and note the applied, failed, skipped and follow-up counts.

2. Download the failed-step CSV and attach it to your change record.

3. Decide, object by object, whether the created users, groups, providers, rules, applications and assignments stay or are removed by hand.

4. If OIDC clients were created, reveal and store their secrets now; if the window has closed, rotate or recreate the client.

5. Record rollback notes in the evidence panel.

6. When your tenant is in a known state, generate a fresh preview and apply again. Re-applying never creates duplicates: existing objects are mapped or skipped.

Automated rollback of one completed run is available through the Portal API. It removes only objects Portal itself created and that are safe to remove: it skips mapped existing objects, groups that now have members, people who have signed in since the apply, and anything it cannot identify with certainty. Contact Cadres support to run it for your tenant.

Record the handoff

The Evidence panel closes out the migration.

• Rollback guidance: a summary, an owner and the steps you would take.

• Communications: whether communications are complete, a summary, and a ticket or document reference.

• Validation: what you checked by hand after cutover.

• Outstanding follow-up: confirm you have reviewed the manual, blocked, skipped and failed steps, and summarise what you did.

Select Save Post-Cutover Evidence. The handoff shows Ready for handoff when an execution record exists, rollback guidance is recorded, communications are confirmed, and follow-up is reviewed. Portal does not hide manual or blocked steps; it lists them so the close is honest.

Keep the inventory fresh during coexistence

If the old system and Portal will run side by side for more than a short window, collect a new inventory before each planning step. A new snapshot shows the drift since the last one. When items were added or removed, re-run the assessment and rebuild the plan before applying. Scheduled collection at an interval between 15 minutes and 7 days is available through the Portal API; ask Cadres support to enable it for your source.

MFA re-enrolment after migration

Portal can carry over time-based authenticator secrets from Okta when the factor inventory and secret-import capabilities are on. Push, passkey and SMS factors cannot be transferred. Each person with such a factor gets a lifecycle event in the Migration lifecycle events panel and must set up MFA again in Portal on first sign-in.

Once a person has re-enrolled, or the event is obsolete, select Mark resolved or Mark superseded on the row and enter a note. This closes the event for your records; it does not change the sign-in requirement, which clears when the person re-enrols.

Retention

• Inventory snapshots and assessments are kept for 90 days after they complete or fail.

• Apply run records are kept for one year.

• Unrevealed one-time secrets from an apply are destroyed after 24 hours.
• Portal never deletes a snapshot that a draft or previewed plan depends on, or an assessment that is still running.

What migration tooling does not do

• It does not overwrite existing Portal objects in merge mode.
• It does not import direct user-to-application assignments.

• It does not test sign-in through the new provider or launch applications for you after cutover. Do that by hand and record it in the evidence panel.

• It does not offer a hidden force-link, force-delete or cross-tenant bypass.

When something goes wrong

Symptom	Likely cause	What to do
Collection fails at once	Capability off, or credential rejected	Turn on the capability, or check the token and its permissions
Snapshot has warnings	An enrichment capability is off	Turn it on and collect again before cutover
Assessment failed	The classifier could not finish	Read the failure detail, fix the cause, run again
Plan actions disabled	Unacknowledged impacts or unresolved overlaps	Work through the Assessment Gate blockers
Apply refused after preview	Your tenant changed after the preview	Generate a new preview and apply again
Invitations show as logged only	Email delivery is not configured	Configure email, then re-send invitations from the user pages
People are in no groups	User inventory was off, or memberships were manual	Turn on the capability, collect, assess and re-plan
Client secret not captured	The one-time reveal was missed	Rotate or recreate the client