Managing identity source transition for AWS IAM Identity Center

AWS Security Blog Managing identity source transition for AWS IAM Identity Center October 20, 2026: This post was republished to reflect the new migration capability from Active Directory to an external identity provider (IdP) or the Identity Center directory, now available in 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 that are switching identity providers (IdPs), consolidating identity infrastructure, adopting new single sign-on capabilities, or migrating off legacy on-premises systems may need to change the identity source in IAM Identity Center. Previously, migrations from Active Directory to another identity source deleted users, groups, memberships, and assignments at the moment of cutover. Now, migrations away from Active Directory preserve your users, groups, memberships, and assignments, just as transitions between an external IdP and the Identity Center directory already do. Only switching to Active Directory still removes users, groups, and assignments. Because the change applies to the entire Identity Center instance at once, test validation and a dress rehearsal are strongly recommended. This post walks you through the migration process and provides sample code 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. Identity source options in IAM Identity Center 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. Each IAM Identity Center instance connects to one identity source at a time. IAM Identity Center supports three main identity sources: - 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 for Microsoft Active Directory. 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. For example, migrating from Active Directory to an external IdP carries your existing users and groups over to the new identity source. IAM Identity Center keeps the same identity store, user IDs, and group IDs, and SCIM updates only the external identifier (externalId) to reflect the new source. How access flows to AWS resources 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. 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 you switch the identity source from Active Directory to an external IdP or to the Identity Center directory, users, groups, user and group IDs, group memberships, and their associated assignments are preserved. Users keep their access to AWS accounts and applications after the new identity source takes over. Switching to Active Directory from any source removes users, groups, and assignments at the moment of cutover, so pre-migration backup and post-migration restoration are still essential in that scenario. What changes when switching identity source in IAM Identity Center Migrations away from Active Directory, and transitions between an external IdP and the Identity Center directory, now preserve users, groups, memberships, and assignments. Transitions to Active Directory removes users, groups, and assignments permanently from IAM Identity Center at the moment of cutover, as shown in the following table. For more information, see Considerations for changing your identity source. | IAM Identity Center item | Status upon switch from AD to external IdP or Identity Center directory | Status upon switch from external IdP or Identity Center directory to AD | | Users and groups in Identity Center | Preserved (same user and group IDs; the externalId changes as the new source takes over) | Deleted (must be re-provisioned from AD) | | Account assignments | Preserved | Deleted (must be recreated) | | Application assignments | Preserved* | Deleted (must be recreated) | Note: *Test each application in a non-production environment before you migrate. Also inventory any assignments that live inside an application itself, because those sit outside IAM Identity Center. Before you start: common blockers - Matching attribute – Confirm which attribute your target IdP uses to find an existing user (sometimes called matching precedence or existing resource lookup). The IdP must take over each existing Identity Center user and group rather than create a duplicate. Test this in a non-production environment. - Required attributes – Every user must have a username, first name, last name, and display name. If any required attribute is missing, that user silently fails to provision. If you send email, it must be unique and single-valued. - Username and NameID – Each user’s IdP userName must exactly match the existing Identity Center username, and the SAML NameID must map to the same value. Decide your sign-in identifier (for example, a legacy sAMAccountName or a UPN) before cutover. - Groups – Confirm that your IdP supports group provisioning through SCIM (for example, Google Workspace provisions users only). Group names must be unique, and renaming a group can cause it to be treated as new, which strands its assignments. Depending on the external Identity provider, users who belong to a group only through a nested group are not provisioned and lose group-based access. Inventory nested groups and directly assign the child groups that contain those users before cutover. - Emergency access – Set up a break-glass administrative access path that does not depend on AWS Identity Center. Sample deployment The following five-step summary (expanded into seven phases in the runbook that follows) 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. Because assignments are now preserved, the restore command is used only for manual rollback. 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. Prerequisites 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 Basic solution walkthrough The following steps summarize the migration process. The next section expands each step with detailed Okta-specific instructions and commands. 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. Store them in a secure, access-controlled location. 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. Each user’s userName in the new source must exactly match the existing Identity Center username, because this is how the new source usually takes over the user. In a test environment, confirm that an existing user is matched, not duplicated. Step 3: Switch IAM Identity Center to the new identity source, and configure sign-in – Update IAM Identity Center to point to the new identity source. For external IdPs, upload the SAML metadata and configure the Assertion Consumer Service (ACS) and issuer URLs in your IdP. Before enabling SCIM (System for Cross-domain Identity Management), confirm that a pilot user can sign in. WARNING: The identity source change applies to the entire Identity Center instance. After you confirm it, Active Directory sync and authentication stop, and users can’t sign in until SAML sign-in works with the new IdP. Users, groups, memberships, and assignments are preserved. Step 4: Enable SCIM provisioning and verify takeover – Enable automatic provisioning and assign users and groups to the IAM Identity Center application in your IdP. The IdP takes over each existing user and group. Then run the validate command to compare the live assignments against your backup and find any 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. Confirm that the identity source shows your external IdP, that users and groups keep the same IDs, and that no duplicates were created. Detailed runbook for Okta migration This runbook covers one of the most common identity source transitions: migrating from an 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, takeover verification, post-migration testing, ongoing cleanup and monitoring, and a documented manual rollback procedure for when things don’t go to plan. If you’re migrating to Active Directory, which still removes users, groups, memberships and assignments, you can adapt the backup and restore scripts from this guide. Phase 1: Plan your pre-migration activities 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. | Stakeholder | Org | Name | Phone | | | Active Directory administrator | Your organization | ||| | AWS administrator | Your organization | ||| | Identity provider (IdP) administrator | Your organization | ||| | Identity Center team/AWS Organizations administrator | AWS account team | ||| | Application owners | AWS account team | ||| | Identity provider (IdP) solutions architect | AWS account team | 1.2 – Inventory current state: Before any changes are made, document the complete current state of your IAM Identity Center configuration. Capture a baseline of all three assignment layers: the users and groups assigned to the IAM Identity Center application in your IdP, the account and application assignments in IAM Identity Center, and any assignments inside the applications themselves: Run the precheck script to export all current Identity Center assignments and principals to CSV. This will produce the following artifacts: assignments.csv – One row per account, permission-set, and principal assignmentprincipals.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. Size the maintenance window using timings from a full-dress rehearsal in a test environment. SCIM provisioning is rate-limited, so for large directories, sync users in batches. 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. - Identity provider (IdP) administrator access (for example, Okta) to configure the IAM Identity Center application, create the SCIM integration, and assign users to the AWS app. - A break-glass or emergency administrative access path that does not depend on the identity source you are migrating. Phase 2: Complete final pre-cutover steps Before starting the cutover, complete the final validation, access, and communication checks described in this phase. 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 users can’t sign in between the identity source change and the new IdP’s sign-in going live, but that their access and assignments are unchanged. - The new sign-in process. After migration, users sign in through your IdP (for example, the Okta My Apps dashboard) or the AWS access portal, depending on the sign-in flow you choose. - 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. - After migration, the d-xxxxxxxxxx.awsapps.com/start access portal URL is no longer supported, and the console shows the supported dual-stack regional URL (https://ssoins-.portal..app.aws) instead, so you must communicate the new URL and update bookmarks/allow-lists. - That the custom access portal alias (friendly URL) isn’t supported after migrating away from Active Directory. If a proxy or bookmark relies on redirect flows, plan to update it. 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: - Run the full migration in a test instance that mirrors your production AD configuration and applications and confirm that existing test users are matched by Okta and not duplicated. - 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. Confirm that the user keeps access to their assigned accounts, permission sets, and applications. Phase 3: Complete the cutover You’re ready to configure Okta, switch the IAM Identity Center identity source, and complete the production cutover. Important: Downtime begins when you confirm the identity source change in Step 3.2 and ends when SAML sign-in works through Okta. Have the Okta application, SAML metadata, and signing certificate ready before you start. Users, groups, memberships, and assignments are preserved. 3.1 – Configure the Okta application: - Sign in to Okta as an administrator. - Navigate to Applications and then to Browse App Catalog. - Search for AWS IAM Identity Center and choose Add Integration. Choose Done. - Choose the newly created app and select the Sign On tab. - Locate the Metadata URL (it will look like: https:///app//sso/saml/metadata ). Open this URL in a new browser tab. - 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. - Download and save the SAML signing certificate from the Sign On tab. 3.2 – Switch the identity source in IAM Identity Center: - In the IAM Identity Center console navigation pane, choose Settings. - Choose Actions and select Change Identity Source. Important: This change applies to the entire Identity Center instance. On the confirmation screen, you must enter ACCEPT to confirm. During this step and before SCIM provisioning is enabled, if the change could not be completed by Identity Center you will see a clear error message in the console to retry changing identity providers. It is safe to retry. - Select External Identity Provider. - Upload the XML metadata file and the SAML signing certificate downloaded from Okta. - Confirm the change. IAM Identity Center will display progress updates as it migrates to the new identity provider. - Don’t enable automatic provisioning yet. Complete Step 3.3 and confirm pilot sign-in in Step 3.4 first. 3.3 – Configure the ACS and issuer URLs in Okta: - In the IAM Identity Center console, choose Settings and then Actions. Select Manage Authentication. - Copy the IAM Identity Center Assertion Consumer Service (ACS) URL and the IAM Identity Center Issuer URL. - Return to Okta and choose Applications and select IAM Identity Center app. Select the Sign On tab and choose Edit. - Under Advanced Sign On Settings, paste the ACS URL and Issuer URL into the corresponding fields. - Choose Save. 3.4 – Confirm pilot sign-in: Before you enable SCIM provisioning, assign an existing pilot user to the IAM Identity Center application in Okta and confirm they can sign in through the AWS access portal. The SAML NameID that Okta sends must exactly match the user’s existing Identity Center username. If sign-in fails, fix the mapping now before proceeding to the next step. 3.5 – Enable automatic provisioning (console) and connect SCIM in Okta: - In the IAM Identity Center console, choose Settings, then choose Enable Automatic Provisioning. Copy and securely record the SCIM endpoint URL and access token. - Return to the IAM Identity Center app in Okta. Choose the Provisioning tab. - Choose Configure API Integration. - Paste the SCIM Endpoint URL into the Base URL field. - Paste the Access Token into the API Token field. - Choose Test API Credentials. You should receive confirmation that the credentials are valid. - Choose Save. - 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.) - On the Push Groups tab, push the groups that are assigned to the AWS application. Group names must exactly match the existing group names in IAM Identity Center. - In the attribute mappings, confirm that userName maps to the existing Identity Center username and that first name, last name, display name, and a single email address are populated. 3.6 – Test SCIM takeover: Before you assign all users, verify that Okta takes over existing users correctly: - In Okta, select an existing pilot user who already exists in IAM Identity Center (People). - Open the user and navigate to the Applications tab. - Assign the AWS IAM Identity Center app to this test user. - Wait 5–10 minutes for SCIM sync to run. - In the IAM Identity Center console, select Users and confirm that the pilot user still has the same user ID, that no duplicate user was created, and that the user’s assignments still work. Note: If the user is duplicated or doesn’t update after 10 minutes, check the Okta System Log for SCIM provisioning errors and verify the SCIM endpoint URL and token are correctly configured. - After the pilot user is taken over successfully, assign the remaining users and groups to the application in Okta. For large directories, assign them in batches. Phase 4: Verify takeover Now that you’ve completed cutover, verify that Okta has taken over all users and groups and that the preserved assignments match your pre-migration baseline. 4.1 – Verify SCIM takeover: Confirm that all production users and groups are provisioned from Okta, that they keep the same user and group IDs, and that no duplicates were created. Check the Okta provisioning logs for errors such as “Refused to create a new, duplicate resource.” 4.2 – Check for assignment drift: Compare the live assignments against the pre-migration CSV If drift is found, the script writes a drift_report.csv file with MISSING and EXTRA entries. Because assignments are preserved, investigate any entries before you continue. Phase 5: Post-migration validation After the cutover, validate end-to-end access for representative user roles and confirm that assignments were preserved. 5.1 – Test end-to-end access: Using a test Okta user account, complete the following validation steps: - Sign in to the Okta Dashboard. - Choose the AWS IAM Identity Center tile under My Apps. - Select an assigned AWS account from the portal. - Confirm that you can assume a role and access the AWS console. - 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. For each application, confirm that user-specific data and settings are intact and that any assignments inside the application still work. Phase 6: Post-migration cleanup and monitoring After confirming the migration is stable, shift focus to ongoing monitoring of provisioning and authentication, and update your operational documentation. 6.1 – Decommission AD only when stable: - 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. Deleting the AD directory removes the manual rollback option and the AD-based access portal endpoint. - The following command will identify disabled users, empty groups, and unassigned permission sets. 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 sign-in 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). Phase 7: Rollback (if needed) Rollback requires manually switching the identity source back to Active Directory, which deletes users, groups, memberships and assignments, and then rebuilding assignments from the pre-migration backup files, as described in the following steps. Note: Define in advance what counts as a failure, who makes the rollback decision, and the acceptable discrepancy threshold. 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: - Navigate to IAM Identity Center and choose Settings, then Actions, and then Change Identity Source. - Select Active Directory as the identity source. - Select your existing AD domain. Ensure AD is still running and reachable before confirming. - Accept the conditions and confirm the switch. Identity Center will display progress updates. - When complete, choose Resume Sync, then choose Start Guided Setup. - Confirm the attribute mappings and select the users and groups to sync. - 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 identity store, create the assignment, and poll until completion, and produce a summary of succeeded, failed, and skipped counts. 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. Troubleshooting the cutover The identity source change in Step 3.2 runs as a sequence of steps: stopping Active Directory sync, disconnecting the directory, and deleting the AD sync profile. If a step after “Stopping Active Directory sync” fails, the Confirm change screen reports which steps failed and offers a Retry failed steps button. You will see one of two error messages, both safe to retry: - “The identity source change could not be completed. Please try again.” — AD sync was stopped but the directory wasn’t disconnected, so new users and changes are not currently syncing from Active Directory. Choose Retry failed steps to complete the transition. If instead you want to stay on Active Directory, choose Start guided setup in the Settings page to reconfigure the sync. - “The identity source change could not be completed. Your identity source has been reverted to Active Directory. Please try again.” — IAM Identity Center automatically rolled back to a healthy AD-connected state, and a banner confirms that AD sync resumed. You don’t need to reconfigure the sync; choose Retry failed steps when you’re ready to try again. Important: In both cases, choose Retry failed steps on the Confirm change screen. If you navigate away from this screen, you can no longer retry the failed steps and will need to restart the identity source change. For troubleshooting tips, see Troubleshooting IAM Identity Center issues. If you have feedback about this post, submit comments in the Comments section below. Conclusion This post covered how to migrate your IAM Identity Center identity source from Active Directory to an external identity provider (Okta), including backing up existing assignments, validating your target identity source, performing the cutover, verifying that the new identity source took over your users and groups with their assignments intact, 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.