Migrate from Okta to FoxIDs

Move Okta sign-ins to FoxIDs using the migration approach that matches where each group of users authenticates. Import local users and let them choose a new password, or enable passwordless login with one-time codes. For social and enterprise sign-ins, configure FoxIDs authentication methods to trust the external identity providers. Okta can also remain an identity provider while applications move to FoxIDs.

This technical guide covers users in Okta Universal Directory, application configuration and account mapping for Okta Identity Engine and Classic Engine.

For local-user imports, convert the reviewed Okta export into a CSV file and use the FoxIDs Seed Tool to bulk load the users into FoxIDs. The CSV examples below show the fields for password setup and passwordless login.

Choose an approach for each group:

Prepare the destination and application

A dedicated test environment lets you try the migration with a small group of users before moving to production. The configuration steps are:

1. If you want a custom domain, configure and verify it on the tenant before configuring applications and external identity providers. Use the resulting FoxIDs URLs throughout the migration. Changing the domain later requires updating external configurations, including application authority or metadata URLs and provider callback and logout URLs.
2. Every environment has a default Login authentication method named login. Customise its branding and login UI to achieve the desired appearance, and adjust its login options for the imported users.
3. Create the authentication methods that connect users to their external identity providers, including Okta if it remains part of the transition.
4. Configure the application, its allowed redirect URLs and logout behaviour, and any APIs that accept its access tokens.

FoxIDs Cloud provides email and SMS delivery for password setup, passwordless login and multi-factor authentication (MFA), depending on the selected FoxIDs Cloud plan.

Configure the required MFA settings and how users will enrol. The CSV imports described here transfer user data, not Okta Verify registrations, FastPass device registrations, passkeys or other MFA enrolments. Users who authenticate locally in FoxIDs enrol in the configured authentication factors. Users who continue authenticating through Okta can retain their Okta enrolments.

Application configuration is a separate workstream from user import. Review issuer, audience, scopes, claims and token validation, plus any Okta SDK or Sign-In Widget dependencies, inline hooks, group rules and application assignments. Recreate the behaviour the application requires. The general migration guide covers the wider application inventory and rollout steps.

Export a defined group of Okta users

Use the Okta Users API to retrieve user data as JSON for conversion. Select the source organisation and the users or groups being migrated. Follow the Link response header's rel="next" URL until all pages have been read. The ordinary list operation omits DEPROVISIONED users; a filter or search query can include them. Search results are eventually consistent, so recent changes may take time to appear.

Retain the source organisation and user id, lifecycle status, required profile attributes and credentials.provider information. Keep Okta-managed, directory-backed and federated users distinguishable. Identity-provider configuration and routing rules help identify where users actually authenticate.

For a report-based export, the User Accounts report provides a CSV Export option. Its columns still need conversion to the FoxIDs Seed Tool format. The API is useful when the import also needs custom attributes or provider information that is absent from the report.

Export group membership and application access separately when they determine permissions. Okta's Group Membership report and User App Access report describe those relationships; they are not all contained in the user's profile object.

Password availability

Okta only offers password-hash exports for migration to Auth0, subject to specific criteria.

FoxIDs can import supported password hashes when they are available.

Map user data and preserve application accounts

FoxIDs creates its own persistent user ID for imported local users. Importing the Okta user id as a custom claim does not make it the FoxIDs user ID or automatically preserve the application's subject. Record the actual OpenID Connect sub or SAML NameID used by each application alongside the source organisation and user ID.

If the application uses the Okta user ID as its sub, import that ID as a custom claim such as legacy_okta_user_id. On the Login authentication method, configure a Map claim transform with action Replace claim, input claim legacy_okta_user_id and output claim sub. The application then receives that value as sub, while the user's persistent FoxIDs ID remains unchanged. If the application uses another subject value, preserve and map that value instead.

Applications that identify accounts by both issuer and subject also need to associate the new FoxIDs issuer with the existing accounts. For SAML applications, configure the required NameID and format on the SAML application registration. A test login shows the actual identity received by the application.

Maintain a mapping between the source identity, the new FoxIDs identity and the existing application account. The identities used during the transition should resolve to the same customer or employee record. For social and enterprise sign-ins, include the identity received directly from the provider; it can differ from the Okta user ID.

For local-user imports, use the following mapping:

Okta lifecycle states have more detail than FoxIDs' disabled flag. The examples enable users selected from ACTIVE accounts and keep suspended accounts disabled. States such as STAGED, PROVISIONED, RECOVERY, PASSWORD_EXPIRED and LOCKED_OUT need an explicit mapping to the intended activation, password-setup or access behaviour.

Migrate social and enterprise sign-ins

Create a FoxIDs authentication method for each social or enterprise identity provider currently connected through Okta, establishing trust directly with that provider. Users retain their accounts and credentials at the provider.

1. Identify the provider behind each connection. Use the relevant provider integration guide, such as Google or Microsoft Entra ID, and select the supported OpenID Connect, SAML 2.0 or WS-Federation authentication method.
2. Register or configure FoxIDs at the provider. Exchange the client settings or federation metadata, and configure the callback and logout URLs specified by the integration guide. Retain the Okta connection during the transition.
3. Allow the new authentication method on the FoxIDs application. Configure Home Realm Discovery so users can select their provider or be routed to it by the configured rules.
4. Map the provider identity to the existing application account. If you need to store per-user claims or access assignments in FoxIDs, configure and provision external users.
5. Recreate access restrictions previously enforced by Okta, including application assignments, suspended users and required MFA.

The expected flow is application → FoxIDs → external identity provider → FoxIDs → application. FoxIDs issues the application's tokens after the provider authenticates the user.

You can try each connection by starting login from the application, selecting the provider and completing its login flow. This lets you observe MFA, the application account and permissions, and logout behaviour.

Migrate users from Active Directory

If Okta delegates password authentication to Active Directory and AD remains the source, FoxIDs can connect directly through Directory Connector for Active Directory. Configure the connector and the Login authentication method as described in that guide. FoxIDs synchronises users from AD and validates passwords against AD, so these users do not need a CSV password import.

By default, FoxIDs saves a local password copy after successful Directory Connector validation. This supports a later move to local FoxIDs authentication by disabling the connector. Users whose passwords have not been captured can use password setup. See the Directory Connector password behaviour for configuration choices.

An AD-sourced user in Okta does not necessarily still authenticate against AD: Okta can migrate password authentication from AD to Okta. The direct connector approach applies when AD still holds and validates the password the user uses.

Migrate passwordless users

Import users as internal FoxIDs users without passwords and configure passwordless login with an email or SMS code. The user enters the code on the login page they have already opened.

This is a change of authentication method for users of Okta FastPass or passkeys. Email and SMS codes do not reproduce FastPass's phishing resistance.

1. Enable email or phone as a login identifier on the FoxIDs Login authentication method, and enable Passwordless with email (one-time password) or Passwordless with SMS (one-time password) as appropriate.
2. For a login method dedicated to passwordless users, select Disable password authentication and disable password setup/reset by email and SMS.
3. Import the users with Password and all password-hash fields omitted. Keep SetPasswordEmail, SetPasswordSms and ChangePassword false. Preserve the mapped verification state, disabled state and required claims.

For example, this Seed Tool CSV imports a fictitious email-passwordless user whose previous email verification state is unknown:

Email;EmailVerified;SetPasswordEmail;SetPasswordSms;ChangePassword;DisableAccount;Claims
alice@example.com;false;false;false;false;false;"[{""Claim"":""legacy_okta_user_id"",""Values"":[""00u000000000DEMO001""]}]"

For SMS users, replace Email and EmailVerified with Phone and PhoneVerified, using the selected phone number and its known verification state. The same upload procedure applies.

You can try the flow with an imported test user by entering their email address or phone number and the received code. A valid code lets an enabled user continue through any required MFA to the application. The user remains without a password after successful passwordless login.

Import users for password setup

Enable email login, password authentication and password setup by email on the FoxIDs Login authentication method. Imported users choose a password during their first login.

User import prepares the accounts. Password setup happens when each user starts a login, not during the import.

Convert the reviewed records into a UTF-8 file for the FoxIDs Seed Tool. Headers are case-sensitive and the separator is a semicolon. This example contains fictitious users whose previous email verification state is unknown; the second account remains disabled:

Email;EmailVerified;SetPasswordEmail;DisableAccount;RequireMultiFactor;Claims
alice@example.com;false;true;false;true;"[{""Claim"":""legacy_okta_user_id"",""Values"":[""00u000000000DEMO001""]}]"
suspended@example.com;false;true;true;true;"[{""Claim"":""legacy_okta_user_id"",""Values"":[""00u000000000DEMO002""]}]"

SetPasswordEmail=true selects password setup by email confirmation. Omit Password and all password-hash columns. RequireMultiFactor=true is the example's chosen policy and requires the corresponding MFA methods to be configured.

Only release the example legacy_okta_user_id claim to applications that need it through their configured claim handling.

Upload users and inspect the result

Use this upload procedure for passwordless users and users who will choose a password at first login, with the fields appropriate to the chosen method.

The Seed Tool splits fields on semicolons; quoted fields cannot contain embedded semicolons or line breaks. Use the Control API user operations if your required values need a richer import representation.

1. Download and configure the Seed Tool for the intended environment. Set SeedSettings.UsersSvcPath to the converted CSV file.
2. Run the Seed Tool and select U to bulk upload the users.
3. Record the new user IDs in your migration mapping.

You can try the upload with a CSV file containing a few users in a test environment. The Seed Tool reports success and failure counts. The imported users can be inspected in FoxIDs Control to see their identifiers, disabled state, claims and password-setup flags.

The Seed Tool uses bulk provisioning, which can replace existing users rather than merge them. A repeated upload can remove credentials and state and create new user IDs. For a partially completed import, reconcile the result before retrying; use targeted user updates for later changes.

Password setup at first login

For an enabled imported user with SetPasswordEmail=true, the expected flow is:

1. The user opens the application and starts login through FoxIDs Login.
2. FoxIDs identifies the user from their email address and sends a confirmation code.
3. The user submits the code and a new password that meets the FoxIDs password policy.
4. FoxIDs verifies the email address, saves the password and clears the password-setup flags. The login continues through any required MFA steps before returning to the application.

Importing a user does not send the setup email. Subsequent password logins use the new FoxIDs password. If a user cannot receive the code, the recovery process needs another way to verify their identity.

You can explore the flow with a test user by following the login steps above. These scenarios show the expected results:

Keep Okta during the transition

FoxIDs can trust Okta as an external identity provider while applications move to FoxIDs. Users authenticate at Okta and FoxIDs issues tokens to the application. This retains Okta passwords and authenticators at Okta; it does not copy them into FoxIDs.

For an OpenID Connect connection:

1. Create an OIDC web application integration in Okta for FoxIDs, using Authorization Code Flow. Assign the users or groups that will sign in through this integration and configure its sign-in policy.
2. Create an OpenID Connect authentication method in FoxIDs. Set Authority to the selected Okta issuer, and configure the Okta client ID under Optional custom SP client ID, its client secret and the matching token-endpoint client authentication method.
3. Request the profile and email scopes as needed; FoxIDs includes openid. Select Read claims from the UserInfo Endpoint instead of the access token or ID token under Show advanced to obtain the user's claims through UserInfo.
4. Register the Redirect URL shown by FoxIDs as a sign-in redirect URI in Okta, and configure the corresponding logout redirect URI where logout is used.
5. Allow the authentication method on the FoxIDs application and configure Home Realm Discovery for the users who continue through Okta.

Okta's org authorization server supports OpenID Connect sign-in with an issuer such as https://example.okta.com. A custom authorization server uses an issuer such as https://example.okta.com/oauth2/default. Use the issuer and claim configuration selected for the integration.

A SAML authentication method is another option: create a SAML application in Okta for FoxIDs and exchange the service-provider and identity-provider metadata and settings.

A test login through the application shows the Okta authentication policy, claims, account mapping and logout behaviour for the new connection. As users move to local FoxIDs login or directly connected providers, route them to those authentication methods. Keeping the application's account mapping aligned across the methods lets it continue using the same account records.

Roll out and retain a rollback path

The migration can be rolled out by application or user group. Users can continue through their usual application URL, with the configured login flow: password setup, a one-time code, their directory password or an external identity provider.

Reconcile users created, changed, suspended or deleted since the export, including group and application-assignment changes. A short change freeze or controlled reconciliation process can keep the source and destination aligned during cut-over. Later updates should preserve credentials and state already established in FoxIDs.

Monitor email and SMS delivery, setup failures, login failures and account-mapping problems. Rollback depends on the previous Okta configuration remaining available. You can try restoring that configuration for a test application to observe the return to the Okta login flow.

A password set locally in FoxIDs is not synchronised back to Okta. A rollback therefore uses the credentials still held by Okta or its connected provider. Users created only in FoxIDs need an access route if rollback is required. Once the required users and applications use their destination authentication methods, the Okta integration can be retired.

Related documentation

• Migration overview
• Upload many users
• Control API user operations
• Login and home realm discovery
• Directory Connector for Active Directory
• OpenID Connect authentication method