Managing identity source transition for AWS IAM Identity Center

September 2, 2026: This post was republished to include Active Directory migration strategies and automation for permission sets.

AWS IAM Identity Center manages user access to Amazon Web Services (AWS) resources, including both AWS accounts and applications. You can use IAM Identity Center to create and manage user identities within the Identity Center identity store or to connect to other identity sources.

Organizations might need to change their identity source configuration as part of a significant transformation to their identity and access management strategy. Common drivers include switching identity providers (IdPs), consolidating identity infrastructure, adopting new single sign-on capabilities, or migrating off legacy on-premises systems. These transitions require planning. A cutover without proper planning can result in temporary loss of access to AWS accounts and applications until assignments are restored..

This blog post walks you through the process of switching from one identity source to another and provides sample code that you can use to assist the transition. It includes architectural guidance and a step-by-step runbook for switching from Active Directory to Okta. This guide helps AWS administrators, identity engineers, and project teams switch identity sources safely.

Note: This walkthrough uses Okta as a representative example of a SAML 2.0 identity provider. The inclusion of Okta in this example does not constitute an endorsement of any specific identity provider.

Each IAM Identity Center instance connects to one identity source at a time. IAM Identity Center supports three main options:

• Identity Center Directory – The default identity store. Users and groups are created and managed directly within IAM Identity Center, with no dependency on an external provider. Suitable for organizations without an existing enterprise directory or those wanting a setup that uses only AWS services.
• Active Directory – Integration with an on-premises Microsoft Active Directory or AWS Managed Microsoft AD through AWS Directory Service. This lets organizations reuse their existing AD identities, group memberships, and access policies.
• External IdP – Integration with third-party providers that support SAML 2.0, including Okta Universal Directory, Microsoft Entra ID (formerly Azure AD), Ping Identity, and others. This is the approach covered in the migration runbook that follows.

The identity source is the definitive system of record: it determines which directory holds the primary copy of user identities and group memberships used for AWS access.

IAM Identity Center grants access to AWS resources in two ways, as shown in Figure 1:

• Permission set assignments – Users or groups are assigned permission sets within specific AWS accounts. This enables assume-role access, and AWS Identity and Access Management (IAM) roles (named AWSReservedSSO_...) are automatically created in each account to back these assignments.
• Application assignments – Users or groups are granted access to AWS-managed applications (such as Amazon SageMaker Studio, Amazon OpenSearch Service and so on) and customer-managed applications integrated with IAM Identity Center.

Figure 1: Granting access to AWS resources for users and groups managed by an identity source in IAM Identity Center

When you change the identity source, the downstream impact on these assignments depends heavily on which sources you’re switching from and to. In some transitions, assignments remain intact.

When switching the identity source from Active Directory to an external IdP, all users, groups, and their associated assignments are deleted from IAM Identity Center at the moment of cutover. This is a disruptive scenario, and it makes pre-migration backup and post-migration restoration of assignments essential steps.

Identity source transitions to or from Active Directory are destructive because users, groups, and all associated assignments are permanently deleted from IAM Identity Center at the moment of cutover. In contrast, transitions between an external identity provider and the local Identity Center directory preserve all users, groups, and assignments, as shown in the following table. For more information, see Considerations for changing your identity source.

Note: For AWS-managed applications that maintain their own identity source reference (such as, SageMaker Studio), the CreateApplicationAssignments API alone might not fully restore access. These applications have dependencies on the original identity sourceID and on specific UserId and GroupId values from the original identity source. They must be restored on a case-by-case basis and might require redeployment. We will cover application migration in part 2 of this blog series.

The following five-step process applies to an identity source transition in IAM Identity Center from Active Directory to Okta, focusing on permission set assignments. The AD-to-Okta runbook in the next section expands each of these steps with specific instructions and commands. To assist users, you can also use the Identity Center migration tool script, which provides a structured workflow for Identity Center migrations with commands for precheck, cutover, validation, and cleanup. The sample scripts and detailed steps are available on GitHub.

Note: This solution is available in the GitHub aws-samples repository. You can report bugs or make feature requests through GitHub Issues. The builders of this solution can help with GitHub issues. Enterprise Support customers can reach out to their Technical Account Manager (TAM) for further questions or feature requests.

Before you start this walkthrough, make sure you have the following prerequisites in place:

• Python 3.10 or later
• AWS credentials configured using environment variables, an AWS configuration file, or a named AWS Command Line Interface (AWS CLI) profile specified with --profile)
• An active IAM Identity Center instance in the target account
• Okta Global Admin access
• Install the migration tool as described in the README file

In this section, we walk you through the basic steps to complete a migration. You will find a detailed Okta example migration walkthrough in the next section.

Step 1: Back up users, groups, and assignments – Before making any changes, export your current identity data such as users, groups, and all assignments. This backup protects you if something goes wrong during migration. The runbook includes a script that exports all current IAM Identity Center assignments and principals to a CSV file, then validates referential integrity.

Step 2: Prepare and validate users and groups in the target identity source – Before switching the IAM Identity Center identity source, confirm that your users and groups exist in the new authoritative source. Verify usernames, display names, email addresses, group names, group memberships and other required attributes. Mismatches in fields like UserName or DisplayName can prevent users from connecting to the new identity source and might cause issues when users try to connect from the new identity source.

Step 3: Switch IAM Identity Center to the new identity source – Update IAM Identity Center to point to the new identity source. For external IdPs, this involves uploading SAML metadata and configuring SCIM (System for Cross-domain Identity Management) for automated provisioning. For Active Directory, this involves selecting your target directory and initiating the sync.

WARNING: When you confirm this change, IAM Identity Center immediately deletes all AD users, groups, account assignments, and application assignments. Users will lose access to AWS accounts and applications and cannot authenticate through the portal until assignments are fully restored in Step 4.

Step 4: Restore assignments – After your new identity source is configured and users and groups have been provisioned into IAM Identity Center, restore all account assignments using the restore script from the runbook. When done, you will run an additional command to find missing or extra assignments.

If drift is found, the script writes a drift_report.csv file with MISSING and EXTRA entries.

Step 5: Validate access – Test access for a sample of users across different roles and permission levels before declaring the migration complete. Confirm that users can authenticate through the new identity source, access their expected AWS accounts, and assume the correct IAM roles.

This runbook covers one of the most common identity source transitions: migrating from a Active Directory to Okta as a SAML 2.0 identity provider.

The sample deployment describes what happens during a transition. It walks through seven phases: stakeholder alignment and pre-migration inventory, pre-cutover validation, the identity source switch itself, assignment restoration, post-migration testing, ongoing cleanup and monitoring, and a documented rollback procedure for when things don’t go to plan.

If you’re migrating between different identity sources, you can adapt the backup and restore scripts from this guide.

Pre-migration planning has four components: stakeholder engagement, inventory, scheduling, and access verification. Complete all four before you schedule the cutover.

1.1 – Document relevant stakeholders:

Fill out this table with actual contact information. You’ll need to reach these people during the cutover window

1.2 – Inventory current state:

Before any changes are made, document the complete current state of your IAM Identity Center configuration:

Run the precheck script to export all current Identity Center assignments and principals to CSV.

```bash 
python -m idc_migration_tool precheck --output-dir ./export 
``` 

This will produce the following artifacts:

• assignments.csv – One row per account, permission-set, and principal assignment
• principals.csv – All users and groups from the identity store

1.3 – Define the cutover window:

Schedule the migration during a low-usage period to minimize user impact. Identify a maintenance window of sufficient length to complete all phases, including time for validation and potential manual rollback (described in Phase 7) if needed. Notify all affected users in advance of the potential temporary disruption to single-sign-on access.

1.4 – Confirm access requirements:

Verify that the following access is confirmed and tested before the cutover window:

• AWS Administrator access to IAM Identity Center and AWS Organizations.
• Okta Administrator access to configure the IAM Identity Center application, create the SCIM integration, and assign users to the AWS app.

With pre-migration plans done, you’re ready to complete the final validation, access, and communication checks required before beginning the cutover.

2.1 – Export IAM Identity Center configuration:

Validate that the backup files generated in Step 1.2 are present and non-empty before proceeding.

2.2 – Communicate impact to users:

Send advance notice to all affected users covering:

• The migration timeline and expected impact window.
• That existing AD-synced users will lose access temporarily during cutover.
• The new sign-in process. After migration, users will access AWS through the Okta dashboard (My Apps) rather than the current AWS access portal.
• Whether the new sign-in flow is IdP-initiated (through Okta) or SP-initiated (through the AWS access portal), and any differences in the user experience.

Prepare a user guide for the new sign-in process and an FAQ for common issues. Schedule a training session to demonstrate how to access AWS through Okta. Ensure your support team is briefed and ready to handle an influx of access issues during and immediately after the cutover.

2.3 – Validate Okta-to-IAM Identity Center sync (pre-cutover testing):

Using a sandbox or test environment if available, perform the following validation steps before executing against production:

• Confirm test users are correctly provisioned from Okta to IAM Identity Center through SCIM.
• Use the AWS Management Console for IAM Identity Center to verify that groups and users appear in Users & Groups with the correct attributes.
• Test the complete end-to-end sign-in flow for a test user. Authenticate through Okta, access the AWS portal, and assume a role in a test account.

You’re ready to configure Okta, switch the IAM Identity Center identity source, and complete the production cutover.

Important: Downtime begins from the moment you confirm the identity source change in Step 3.2, AD users, groups, and all account and application assignments are immediately deleted. Users will not be able to access IAM Identity Center until Phase 4 (assignment restoration) is complete.

3.1 – Configure the Okta application:

1. Sign in to Okta as an administrator.
2. Navigate to Applications and then to Browse App Catalog.
3. Search for AWS IAM Identity Center and choose Add Integration. Choose Done.
4. Choose the newly created app and select the Sign On tab.
5. Locate the Metadata URL (it will look like: https://<your-okta-domain>/app/<app-id>/sso/saml/metadata). Open this URL in a new browser tab.
6. An XML file will render in the browser. Save this file. This is your SAML metadata file, which will be uploaded to IAM Identity Center.
7. Download and save the SAML signing certificate from the Sign On tab.

3.2 – Switch the identity source in IAM Identity Center:

1. In the IAM Identity Center console navigation pane, choose Settings.
2. Choose Actions and select Change Identity Source.
   

   Important: This action is irreversible. On the confirmation screen, you must enter ACCEPT to confirm. Immediately upon confirmation, all AD users, groups, account assignments, and application assignments are deleted from IAM Identity Center.

3. Select External Identity Provider.
4. Upload the XML metadata file and the SAML signing certificate downloaded from Okta.
5. Confirm the change. IAM Identity Center will display progress updates as it migrates to the new identity provider.
6. After the identity source change is confirmed, choose Enable Automatic Provisioning.
7. Copy and securely record the SCIM Endpoint URL and Access Token that are generated. You will need these in the next step.

3.3 – Configure SCIM provisioning in Okta:

1. Return to the IAM Identity Center app in Okta. Choose the Provisioning tab.
2. Choose Configure API Integration.
3. Paste the SCIM Endpoint URL into the Base URL field.
4. Paste the Access Token into the API Token field.
5. Choose Test API Credentials. You should receive confirmation that the credentials are valid.
6. Choose Save.
7. On the Provisioning page, choose Edit and under To App enable all three provisioning options (Create Users, Update User Attributes, and Deactivate Users). Choose Save. (The To App settings control how Okta provisions users to IAM Identity Center. All three options are required for the migration to work correctly.)

3.4 – Configure the ACS and issuer URLs in Okta:

1. In the IAM Identity Center console, choose Settings and then Actions. Select Manage Authentication.
2. Copy the IAM Identity Center Assertion Consumer Service (ACS) URL and the IAM Identity Center Issuer URL.
3. Return to Okta and choose Applications and select IAM Identity Center app. Select the Sign On tab and choose Edit.
4. Under Advanced Sign On Settings, paste the ACS URL and Issuer URL into the corresponding fields.
5. Choose Save.

3.5 – Test SCIM user sync:

Before restoring assignments, verify that SCIM provisioning is working correctly end-to-end:

1. In Okta, create a test user (People and then Add Person).
2. Open the user and navigate to the Applications tab.
3. Assign the AWS IAM Identity Center app to this test user.
4. Wait 5–10 minutes for SCIM sync to run.
5. In the IAM Identity Center console, select Users and confirm the test user appears with the correct attributes.
   

   Note: If the test user doesn’t appear after 10 minutes, check the Okta System Log for SCIM provisioning errors and verify the SCIM endpoint URL and token are correctly configured.

6. After the test user appears, you can sync the full list of users to IAM Identity Center.

Now that you’ve completed cutover, you need to verify that all users and groups have been synchronized, restore the account and application assignments, and allow time for the changes to propagate.

4.1 – Verify SCIM sync:

Before running the restore script, confirm that all production Okta users and groups are provisioned and visible in IAM Identity Center. The restore script matches users by UserName and groups by DisplayName—any users or groups that aren’t yet synced will result in failed assignment restores.

4.2 – Restore assignments using a script:

Recreate the assignments from the pre-migration CSV file.

```bash 
python -m idc_migration_tool cutover --csv ./export/assignments.csv 
```

This script matches principal names in the new identity store, creates assignments, and reports success or failure for each.

4.3 – Wait for propagation:

AWS might take several minutes to propagate role assignments after restoration. Allow 5–10 minutes before beginning validation testing.

With the cutover complete and access and assignments propagated, you can now validate end-to-end access, test representative user roles, and confirm that all assignments have been restored accurately.

5.1 – Test end-to-end access:

Using a test Okta user account, complete the following validation steps:

1. Sign in to the Okta Dashboard.
2. Choose the AWS IAM Identity Center tile under My Apps.
3. Select an assigned AWS account from the portal.
4. Confirm that you can assume a role and access the AWS console.
5. Test role switching within the console to validate permission boundaries.

5.2 – Spot-check multiple user types:

Validate access for a representative sample of users across different access levels, including Administrator, Developer, Read-Only or Audit, and any other standard roles defined in your environment. Confirm that permission sets are correctly mapped and that no unintended access has been granted or denied.

Additionally, use the following script to compare the pre-migration CSV file against the current live state to detect missing or extra assignments.

```bash 
python -m idc_migration_tool validate --csv ./export/assignments.csv --output-dir ./export 
```

If drift is found, the script writes a drift_report.csv file with MISSING and EXTRA entries.

With the transition complete and tested, it’s time to remove obsolete resources, monitor provisioning and authentication, and update operational documentation to reflect the new identity configuration.

6.1 – Clean up old resources:

• Manually delete any unused AD-synced IAM roles if IAM Identity Center hasn’t automatically cleaned them up.
• Don’t decommission the Active Directory domain controllers until you’re confident the migration is stable and rollback is no longer needed. Keep AD online as a fallback.
• The following command will identify disabled users, empty groups, and unassigned permission sets.

  ```bash 
  # Report only 
  python -m idc_migration_tool cleanup 
   
  # Report and prompt for deletion 
  python -m idc_migration_tool cleanup --delete 
  ```

6.2 – Monitor SCIM sync:

• Confirm that SCIM provisioning continues to run without errors in the days following migration
• Monitor new user onboarding from Okta to verify that newly created Okta users are automatically provisioned into IAM Identity Center
• Review IAM Identity Center and AWS CloudTrail logs for failed signin attempts or unexpected authentication errors

6.3 – Update documentation:

Update all internal documentation to reflect the new identity architecture:

• Record the SCIM integration details, SAML metadata links, and new group-to-permission-set mappings.
• Update internal SOPs and onboarding guides to reflect the new Okta-based login process.
• Document troubleshooting procedures for the most common failure modes.

6.4 – Post-migration checklist:

Before closing the migration project, confirm all of the following:

• Users can authenticate successfully through Okta
• Permission sets are correctly assigned to the correct users and groups
• Account assignments are working correctly across accounts
• Monitoring and logging are configured and alerting on anomalies
• Internal documentation and SOPs are updated
• Support team is trained on the new login process
• Rollback procedures have been reviewed and are ready if needed
• Active Directory integration cleanup is scheduled (do not rush decommission)

IAM Identity Center doesn’t retain AD users, groups, or account assignments after an identity source switch. The configurable AD sync is also deleted. A rollback requires manually switching the identity source back to Active Directory and rebuilding all assignments and identities from the pre-migration backup files. The deleted data cannot be automatically restored.

Note: Only initiate rollback if the Okta migration has failed and cannot be recovered within the migration window. Rollback is a manual, time-consuming process. There is no single-button undo for an identity source switch.

7.1 – Switch identity source back to Active Directory:

1. Navigate to IAM Identity Center and choose Settings and then Identity Source.
2. Select Active Directory as the identity source.
3. Select your existing AD domain. Ensure AD is still running and reachable before confirming.
4. Accept the conditions and confirm the switch. Identity Center will display progress updates.
5. When complete, choose Resume Sync, then choose Start Guided Setup.
6. Confirm the attribute mappings and select the users and groups to sync.
7. Review and save the configuration.

7.2 – Wait for AD users and groups to repopulate:

After completing the guided setup, AD users and groups will begin to reappear in IAM Identity Center through the directory sync. This might take several minutes depending on the size of your directory.

7.3 – Recreate account assignments:

Recreate the assignments from the pre-migration CSV file. This will resolve each principal name in the new identity store, create the assignment, and poll until completion, and produces a summary of succeeded, failed, and skipped counts.

```bash 
python -m idc_migration_tool cutover --csv ./export/assignments.csv 
```

7.4 – Validate access:

Confirm users can authenticate using the original AD-based AWS access portal URL and can access their expected AWS accounts and roles. Test key role types (such as Admin, Developer, and Audit) before declaring rollback complete.

For troubleshooting tips, see Troubleshooting IAM Identity Center issues.

In this post, we showed you how to migrate your IAM Identity Center identity source from Active Directory to an external identity provider (Okta). We covered the end-to-end process: backing up existing assignments, validating your target identity source, performing the cutover, restoring assignments, validating access, and rolling back if needed.

For the backup and restore scripts referenced in this guide, see the aws-samples GitHub repository. For more information about IAM Identity Center configuration and permission set management, visit the AWS Security Blog and the AWS IAM Identity Center documentation.

If you have feedback about this post, submit comments in the Comments section below.