AWS Builder Center

Align Your IAM Identity Center Usernames for a Seamless SCIM Migration

Demonstrates how to rename IAM Identity Center users in-place for SCIM-matched external IdP migrations using the Identity Store API's UpdateUser operation.

How to Bulk-Rename IAM Identity Center Users Before Switching to an External IdP

You're migrating IAM Identity Center from its built-in directory to an external Identity Provider — Microsoft Entra ID, Okta, or another SCIM-capable IdP. Everything is planned. But when you enable SCIM provisioning, it creates duplicate users instead of linking to the existing ones. What happened?
SCIM matches users by  userName . If your existing IAM Identity Center usernames (e.g.,  jdoe@agency.gov ) don't match the external IdP's User Principal Name format (e.g.,  ECA.JDoe@agency.gov ), SCIM sees them as new users rather than existing ones. The result: duplicate accounts, broken access, and a stalled migration.
The solution is simple. The Identity Store API's  UpdateUser  operation supports modifying the  userName  attribute in-place — group memberships, permission set assignments, and MFA devices are all linked to the immutable  UserId , not the username, so they stay intact.
In this sample, you'll see how to map your current usernames to the target format using a CSV mapping file and perform the bulk rename with a single script invocation.
The  sample-idc-user-rename-utility  on aws-samples provides a reference implementation that performs this bulk rename safely — with pre-run validation, adaptive retries, interrupt safety, and automatic rollback generation. Use it directly or adapt it to your organization's migration workflow.

Why In-Place Renames Work

IAM Identity Center stores assignments and group memberships against an internal, immutable  UserId  — not the  userName . When you call  UpdateUser  to change the  userName , everything else stays intact:
  • ✅ Permission set assignments — unchanged
  • ✅ Group memberships — unchanged
  • ✅ MFA devices — unchanged
  • ✅ Application assignments — unchanged
The only thing that changes is the sign-in name for the IAM Identity Center access portal.

The Migration Workflow

This utility drives the cutover workflow for an IDC-to-external-IdP migration:
  1. Dry Run — validate the CSV, preflight credentials and permissions, preview all renames without modifying anything
  1. Rename — execute the live rename ( GetUserId  →  UpdateUser  per row); writes a rollback CSV automatically
  1. Switch — change the identity source in IAM Identity Center to External Identity Provider
  1. Enable SCIM — the external IdP syncs and matches users by  userName 
  1. Verify — confirm user sign-in through the access portal is working
five part diagram showcasing each step along the workflow


How It Works

Prepare a two-column CSV mapping current usernames to their target format:
Current Username,New Username
jdoe@example.gov,ECA.JDoe@example.gov
asmith@example.gov,ECA.ASmith@example.gov
Then run a dry-run to preview what will happen:
pip3 install -r requirements.txt
python3 rename_idc_users.py --idc-id d-1234567890 --csv user_mapping.csv --dry-run
Example dry-run output:
2026-07-30 13:45:01 INFO rename_idc_users.py:301 - ============================================================
2026-07-30 13:45:01 INFO rename_idc_users.py:302 - IAM Identity Center User Rename
2026-07-30 13:45:01 INFO rename_idc_users.py:303 - Identity Store: d-1234567890 | Region: us-east-1
2026-07-30 13:45:01 INFO rename_idc_users.py:304 - Mode: DRY RUN
2026-07-30 13:45:01 INFO rename_idc_users.py:305 - ============================================================
2026-07-30 13:45:01 INFO rename_idc_users.py:87 - Skipping header row: Current Username,New Username
2026-07-30 13:45:02 INFO rename_idc_users.py:245 - [1/2] jdoe@example.gov → ECA.JDoe@example.gov ... DRY RUN (would rename UserId=94813a48-...)
2026-07-30 13:45:02 INFO rename_idc_users.py:245 - [2/2] asmith@example.gov → ECA.ASmith@example.gov ... DRY RUN (would rename UserId=7f2c19b6-...)
2026-07-30 13:45:02 INFO rename_idc_users.py:270 - ============================================================
2026-07-30 13:45:02 INFO rename_idc_users.py:271 - SUMMARY
2026-07-30 13:45:02 INFO rename_idc_users.py:272 - Renamed: 2
2026-07-30 13:45:02 INFO rename_idc_users.py:273 - Not found in IdC: 0
2026-07-30 13:45:02 INFO rename_idc_users.py:274 - Target exists, source absent: 0
2026-07-30 13:45:02 INFO rename_idc_users.py:275 - Errors: 0
2026-07-30 13:45:02 INFO rename_idc_users.py:276 - ============================================================
2026-07-30 13:45:02 INFO rename_idc_users.py:290 - Full log saved: rename_log_20260730_174502Z.json
When you're confident, execute the live run:
python3 rename_idc_users.py --idc-id d-1234567890 --csv user_mapping.csv
The script prompts for confirmation before making changes. After completion, it writes a rollback CSV that reverses the operation — feed it back into the same script to undo everything:
python3 rename_idc_users.py --idc-id d-1234567890 --csv rollback_20260730_140000Z.csv

Architecture

architecture and data flow for sample code


Safety Features

The sample includes several layers of protection for production use, including:
  • Pre-run CSV validation — detects conflicting mappings (duplicate sources, duplicate targets, chained renames) and aborts before any API call
  • Preflight permission checks — validates credentials, IAM permissions, and the Identity Store ID with a single API call before processing rows
  • Interrupt safety — rollback CSV and JSON audit log are written even on Ctrl-C, so renames already applied always have a rollback path
  • Adaptive retries — boto3's adaptive retry mode handles API throttling automatically
See the  repository README  for full details on ambiguity detection, case-insensitive matching, and the JSON log structure.

CI/Automation Flags

For automated pipelines:
  •  --yes  — Skip the interactive confirmation prompt
  •  --strict  — Exit non-zero if any row didn't result in a rename (useful as a CI gate)
  •  --output-dir  — Redirect output files to a specific directory (validated writable before any rename begins)

IAM Policy

The minimum required permissions:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"identitystore:GetUserId",
"identitystore:ListUsers",
"identitystore:UpdateUser"
],
"Resource": "*"
}
]
}

When to Use This

  • IDC-to-Entra ID migration — The most common case: organizations adopting Microsoft Entra ID as their external IdP where UPN formats differ from existing IDC usernames
  • Any external IdP with SCIM — Okta, OneLogin, Ping Identity — any provider where SCIM sync requires matching usernames
  • Username standardization — Bulk format changes (e.g.,  firstname.lastname@org.gov  →  ECA.FLast@org.gov ) before enabling SCIM

Data Privacy Considerations

The CSV mapping file contains usernames (typically email addresses), which are PII. Don't commit real mapping files to version control. The generated rollback CSV and JSON audit log also contain usernames — store them securely, restrict access, and delete when no longer needed.

Get Started

The sample is available on GitHub under the MIT-0 license:
Clone the repository, prepare your CSV, run a  --dry-run , and you're ready for cutover day. If you find it useful, give the repo a ⭐ or open an issue with feedback.

Related Resources



Tags: AWS IAM Identity Center, SCIM, Identity Provider, Migration, Microsoft Entra ID, Python, Identity Store API
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article