Managing identity source transition for AWS IAM Identity Center

What it is

A seven-phase runbook from AWS for migrating AWS IAM Identity Center's identity source from Active Directory to Okta (as a representative SAML 2.0 IdP), paired with a GitHub migration tool (aws-samples repo) providing precheck, cutover, validation, and cleanup commands.

How it works

The cutover (Phase 3) is a single irreversible action in the IAM Identity Center console: Settings → Actions → Change Identity Source, which requires typing ACCEPT to confirm. The moment this is confirmed, all AD users, groups, account assignments, and application assignments are deleted — there is no staged or gradual transition. Recovery depends entirely on CSV backups (assignments.csv, principals.csv) taken beforehand and a restore script that matches principals by UserName (users) and DisplayName (groups) in the new identity store to recreate assignments. A separate drift-detection command compares the pre-migration CSV against live state and writes a drift_report.csv with MISSING/EXTRA entries.

flowchart TD
    A[Phase 1-2: Backup + validate] --> B[Phase 3: Confirm cutover ACCEPT]
    B --> C[All AD users/groups/assignments deleted]
    C --> D[Phase 4: Restore from CSV backup]
    D --> E{Drift report clean?}
    E -->|Yes| F[Phase 5: Validate access]
    E -->|No| G[Phase 7: Manual rollback to AD]
    G --> H[Re-sync AD, rebuild assignments from same CSV]

Preconditions / Affected

Applies specifically to transitions to/from Active Directory — these are destructive. Transitions between an external IdP and the local Identity Center directory, by contrast, preserve all users, groups, and assignments (stated explicitly as the non-destructive case). Requires Python 3.10+, AWS admin access to IAM Identity Center/Organizations, and Okta Global Admin access. AWS-managed apps with their own identity source reference (e.g., SageMaker Studio) are called out as not fully restorable via CreateApplicationAssignments alone — they depend on the original identity source ID and specific UserId/GroupId values, and may require redeployment (full coverage deferred to "part 2" of the series, not yet published per this post).

What to do

• Run the precheck script before cutover to export assignments.csv and principals.csv.
• After cutover, enable automatic provisioning in Identity Center, configure SCIM in Okta (Base URL = SCIM Endpoint, API Token = Access Token), and enable all three "To App" provisioning options (Create Users, Update User Attributes, Deactivate Users) — all three are required.
• Configure ACS URL and Issuer URL from Identity Center's "Manage Authentication" page into Okta's Advanced Sign On Settings.
• Test SCIM sync with one test user before syncing the full population.
• Run the restore script against the backup CSV, wait 5–10 minutes for propagation, then run the drift-check command.
• Do not decommission AD domain controllers until migration stability is confirmed — keep AD online as rollback fallback.

Caveats

Rollback (Phase 7) is manual only — there is no automated undo. It requires AD still being reachable, re-running guided directory sync, and rebuilding all assignments from the same pre-migration CSV, with no automatic restoration of deleted data. The post itself flags the application-assignment restoration gap for AWS-managed apps as unresolved in this installment.