Migrate your human, non-Okta user accounts to Universal Directory

Introduction

Your company has adopted the Okta platform and wants to use Universal Directory as the single point of identity access management for all its users. This gives it access to Okta's full complement of User Access Management (opens new window) features and functionality. To do this, you need to migrate user identities from a source provider, such as a local Active Directory, LDAP server, or third-party identity provider.

Devise a user migration strategy based on your company's needs, timelines, and source data. Configure Universal Directory to receive the new identities and assign them to the correct apps and APIs. Prepare the source provider and its contents for migration, and then import your data. Use the KPIs you've identified as part of your strategy to measure your success.

Learn

Learn the basics that you need to lay the foundations for your work:

• Universal Directory (UD) is the central store for user information in your Okta org.
• The Users API (opens new window) provides operations to create user accounts in your org.
• The Groups API (opens new window) provides operations to manage Okta groups and their user members.
• Password import inline hooks help to move users' password to UD from a source provider during migration.

Plan

Plan your migration around four key points:

• What data are you migrating?: Identify the users and groups to migrate. Then, identify the IAM data to import into UD vs the profile data that needs to go elsewhere, and the apps they need to access. Validate the data quality. Consider data privacy and regulations.
• Migration type: Choose between a one-time migration and a phased program. The one-time approach moves all users and credentials at once. In contrast, a phased program moves data slowly over time. The source provider stays active during this on-demand process. Base your decision on your current user store and your deadlines.
• End-user experience: Decide on the right migration experience for your users. Determine if you want to prioritize convenience or immediate security. Select a seamless migration to offer a frictionless user experience. This keeps users unaware that their accounts have been migrated. Select a staged migration to take advantage of Okta's features. This improves security right away but requires user action.
• Measuring success: Define KPIs to measure the worth and success of your migration. Try to balance the inherent value of the project with a lack of user disruption and overall security goals.

With your strategy set using the Plan section, and the implementation using the guides in the next section, create the following test and rollback plans:

• Create a realistic set of test data and test your migration.
• Create a rollback plan for the migration.

Build

You’re now ready to build your migration solution. In this section, you execute your migration strategy from start to finish. First, you prepare Universal Directory to receive your users. Then, you connect your apps and perform the user import.

Run your strategy

To execute your migration strategy, begin by configuring the user account profiles for the new users. Then, configure the groups thatyou want them to belong to, and the apps they can access. Connect your apps and APIs to Okta, and then import your users.

Configure Universal Directory

Prepare Universal Directory to receive the new user accounts:

• Create your needed user groups. Use the Admin Console (opens new window) if you prefer a GUI or the Groups API (opens new window) if you prefer to script.
• Create a user profile (opens new window) for the new user accounts.
• Set the authentication factors (for example, password, email, phone) that users must use to validate their identity with an authenticator enrollment policy (opens new window).

Connect your apps and APIs to Okta

Your apps and API can't use your source provider to authenticate users post-migration. Ensure that your apps and API can authenticate your users with both Okta and your source provider:

• Search the OIN catalog (opens new window) for Okta-enabled versions of your third-party apps.
• Update your apps to use Okta as an identity provider:
  • Update your app's sign-in form to connect to Okta.
  • Make your app a multi-tenant OIDC app with Okta as an additional identity provider (opens new window).
• Update your APIs to use Okta as an identity provider
• Create authentication policies for your apps and APIs (opens new window) that mirror the existing sign-in experience with the source provider, or that enhance it as you’ve planned.

Note: Contact your Technical Account Manager for further assistance migrating your apps to Okta.

Import your user accounts into Universal Directory

Extract the user data from the source provider into an intermediate staging area. Clean up that data so that it's consistent and contains only valid information as you did for the test.

For a seamless, one-time migration, where users are unaware their account has been moved, import each user's hashed password with their details. Then, make their account active:

• Use the Users API to create active user accounts with the hashed password.
• Send users notification to sign in normally.

For a one-time migration with authentication reset, where users must reset their authentication details to activate their account, import each user's details, and make their account staged:

• Use the Users API to create staged user accounts without credentials.
• Alternatively, you can bulk import user details from a CSV file (opens new window).
• Send users notification to reactivate their accounts. (Mass-select users in Okta and click Activate to send Welcome/Set Password emails.)

For a migration program, where user passwords are migrated when they first sign in to an app from the source provider:

• Create a password import inline hook to one of the following places:
  • Local Active Directory or LDAP server
  • Third-party identity provider
• Use the Okta Users API to create active user accounts with the provider type and name set to IMPORT, and the inline hook attached.
• Send that user a notification to sign in through the standard Okta process.

If your system uses Active Directory agents to synchronize passwords with Okta for SSO, you can also use the AD Agent to migrate passwords to Okta (opens new window).

If you’ve stored your user's non-IAM profile data in another system, use the User ID returned by the Users API as a reference point to connect it. Find the user IDs after creation by calling List all users (opens new window).

End the migration program (if applicable)

When you plan a migration program, you set a fixed period to leave the inline hook in service. At the end of this period, most your users have migrated their account. At this point, you can do one of two things:

• Use the User Credentials API (opens new window) to force a password reset for users that still have credentials.provider.type set to IMPORT. Those users receive an email to set their password with a link to follow.
• Consider those users as stale accounts who must recreate their accounts to gain access to your apps again.

Finally, you can retire your legacy system from service.

Congratulations, you have successfully designed and implemented a migration plan for your user accounts to Universal Directory. After the accounts are activated, your new user accounts are stored and assigned the correct types, roles, groups, and attributes.

These accounts also link to the user's original account in the source Data Store, if needed. The KPIs you have set as part of the plan keep you mindful of the requirements for its success. Your users don't know that the migration has taken place unless you've designed it that way.

Related topics

To complement your user migration campaign, consider a way to provision and deprovision applications to your new users.

• Adding a SCIM interface to your apps allows admins to control user access centrally.
• Search the Okta Integration Network (opens new window) for provisioning flows and SCIM-ready apps that exist.

Learn more about working with non-human identities (NHIs):

• Okta secures AI (opens new window)
• What is non-human identity security? (opens new window)
• The non-human identity lifecycle (opens new window)