Migrate from Auth0 to FoxIDs

Move Auth0 sign-ins to FoxIDs using the migration approach that matches each connection. Import database users with bcrypt password hashes or let them choose a new password. Import passwordless users without passwords and enable one-time codes. For social and enterprise sign-ins, configure FoxIDs authentication methods to trust the external identity providers.

This technical guide covers application configuration, user import and account mapping for Auth0 database, email/SMS passwordless, social and enterprise connections.

For database and passwordless users, convert the reviewed Auth0 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 each migration approach.

Choose a method for each group before preparing the import:

Imported password and passwordless users authenticate locally in FoxIDs. Social and enterprise users authenticate at the connected identity provider.

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 social and enterprise users to their external identity providers, following the relevant migration section below.
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 imports described here do not transfer Auth0 MFA registrations. For password accounts, review password length, complexity and expiry requirements: importing a hash skips password policy validation during import, but the selected policy applies when the user signs in.

Application configuration is a separate workstream from user import. Review issuer, audience, scopes, claims and token validation, plus any Auth0 SDK assumptions, Actions, organisation membership and role assignments. Reimplement the behaviour the application requires. The general migration guide covers the wider application inventory and rollout steps.

Export a defined group of Auth0 users

Follow Auth0's bulk user export instructions. Select the source connection explicitly with connection_id; an API export without it includes all connections. Keep database, passwordless and federated users distinguishable throughout conversion.

Use JSON-compatible export (NDJSON) as the source for your conversion. Auth0 CSV exports apply additional escaping, so they are not ready-made FoxIDs Seed Tool input. A small export can be used to try the conversion to the Seed Tool CSV format.

Include user_id, blocked and the identifiers and verification state used by each connection: email and email_verified, or phone_number and phone_verified for SMS users. For social, enterprise and linked accounts, retain the provider, connection and user ID from identities for account mapping. Export only the user data needed after migration, and keep the source tenant and connection alongside the export. Consult the Auth0 user profile schema when selecting fields.

Obtain password hashes when retaining passwords

Request the password-hash export through Auth0 Support. It is separate from the user data export. Auth0's password-hash export guide describes the NDJSON records and the passwordHash field. Its $2b$10$... example identifies bcrypt variant 2b and cost 10.

Match each hash to the correct user using the source tenant, database connection and user ID.

Map user data and preserve application accounts

FoxIDs creates its own persistent user ID for imported local users. Importing an Auth0 user_id as a custom claim does not make it the FoxIDs user ID or automatically preserve the application's sub claim. For social and enterprise sign-ins, verify the identity received directly from the provider and the subject FoxIDs issues to the application.

To retain the Auth0 user ID as the application's sub, import it as a custom claim such as legacy_auth0_user_id. On the Login authentication method, configure a Map claim transform with action Replace claim, input claim legacy_auth0_user_id and output claim sub. The application then receives the Auth0 user ID as sub, while the user's persistent FoxIDs ID remains unchanged.

Maintain a mapping between the source identity, the new FoxIDs identity and the existing application account. For example, the old Auth0 identity and the new FoxIDs identity should both resolve to the same customer record during the transition, not create two customer records. Verify the actual subject issued to each application and update its account mapping where necessary. Do not link accounts solely because their email addresses match.

For local-user imports, use the following mapping:

Migrate social and enterprise sign-ins

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

1. Identify the provider and configuration behind each Auth0 connection. Use the relevant provider integration guide, such as Google, Facebook 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 Auth0 configuration 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. Reconcile the provider identity with the existing application account. The identifiers returned during a test login can be compared with the source account; an Auth0 user ID is not necessarily the identifier returned directly to FoxIDs. If you need to store per-user claims or access assignments in FoxIDs, configure and provision external users.
5. Recreate any restrictions previously enforced by Auth0, including blocked users and organisation access.

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 passwordless users

Import users from Auth0's email or SMS passwordless connections as internal FoxIDs users without passwords. Configure passwordless login so they continue signing in with a one-time code. Users who previously received an Auth0 magic link instead enter a one-time code on the login page they have already opened. This avoids asking users to follow sign-in links in emails or SMS messages.

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. This keeps the login flow focused on one-time codes.
3. Import the users with Password and all password-hash fields omitted. Keep SetPasswordEmail, SetPasswordSms and ChangePassword false so users are not required to choose a password. Preserve verification state, disabled state and required claims.

To try passwordless login, you can start login with an imported test user's email address or phone number and enter the received code. A valid code lets an enabled user continue through any required MFA to the application; invalid or expired codes and disabled accounts do not grant access.

For example, this Seed Tool CSV imports a fictitious email-passwordless user:

Email;EmailVerified;SetPasswordEmail;SetPasswordSms;ChangePassword;DisableAccount
alice@example.com;true;false;false;false;false

For SMS users, replace Email and EmailVerified with Phone and PhoneVerified, using the reviewed phone number and verification state. The same upload procedure applies. The user remains without a password after successful passwordless login.

Import users with bcrypt password hashes

FoxIDs accepts complete bcrypt strings with $2a$, $2b$ or $2y$ prefixes and costs from 4 to 16. For users whose hashes are outside the supported format, use password setup by email.

Enable email login and password authentication on the FoxIDs Login authentication method for these users.

Copy each matched Auth0 passwordHash value into the CSV's PasswordHash column and set PasswordHashAlgorithm to bcrypt. Preserve the entire hash string, including its variant, cost and embedded salt. It is already encoded for bcrypt. See password hash formats and the Control API password import contract.

For the Seed Tool, use the following columns. This is a synthetic test account; replace it with your reviewed export:

Email;EmailVerified;PasswordHashAlgorithm;PasswordHash;SetPasswordEmail;ChangePassword;DisableAccount
alice@example.com;true;bcrypt;$2b$10$..CA.uOD/eaGAOmJB.yMBu3YunYvFEoaS5IJZ/wiqfQ/EWx.HaqjC;false;false;false

Omit Password and PasswordHashSalt. Keep SetPasswordEmail, SetPasswordSms and ChangePassword false when the user should continue with the existing password. Preserve disabled state, verification state, claims and MFA requirements from the reviewed mapping. Include PasswordLastChanged when you know the original change time, in Unix seconds; otherwise FoxIDs records the import time for password-age checks.

The same upload procedure applies to all local-user imports. Bulk provisioning can replace an existing account and its credentials, regardless of the chosen password format.

With an imported test user, you can try login with the original password and repeat it with an incorrect password. The original password authenticates the user subject to the configured password policy and MFA; an incorrect password or a disabled account does not grant access. Password change and recovery can also be tried through the configured Login UI.

The imported hash remains bcrypt after login. A password set or changed in FoxIDs is stored using FoxIDs' default PBKDF2 format. Password history continues to prevent reuse according to the selected policy, including when an old bcrypt hash is retained after a password reset.

Import users for password setup

Use this method for accounts that will choose a new password instead of importing a hash. Enable email login, password authentication and password setup by email on the FoxIDs Login authentication method. For users who should continue without a password, follow Migrate passwordless users.

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 with previously verified email addresses; the second account remains disabled:

Email;EmailVerified;SetPasswordEmail;DisableAccount;RequireMultiFactor;Claims
alice@example.com;true;true;false;true;"[{""Claim"":""legacy_auth0_user_id"",""Values"":[""auth0|demo-001""]}]"
blocked@example.com;true;true;true;true;"[{""Claim"":""legacy_auth0_user_id"",""Values"":[""auth0|demo-002""]}]"

SetPasswordEmail=true selects password setup by email confirmation. Omit Password and all password-hash columns. You do not need a temporary shared password or ChangePassword for this flow. RequireMultiFactor=true is the example's chosen policy and requires the corresponding MFA methods to be configured.

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

Upload users and inspect the result

Use this upload procedure for users with bcrypt hashes, 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 safely merge them. Check for collisions before uploading. Do not rerun the full file after users have set passwords or gained access: replacement can remove credentials and state and create new user IDs. Reconcile a partially completed import before retrying; handle later changes through reviewed, targeted user updates.

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, not the previous Auth0 password. If a user cannot receive the code, use an approved recovery process that verifies identity.

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

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: their existing password, password setup, a one-time code or their existing external identity provider.

Before each production import, reconcile users created, changed, blocked or deleted since the export. Define a short change freeze or another controlled reconciliation process. Do not overwrite users who have already migrated as a way to apply these changes.

Monitor email and SMS delivery, setup failures, login failures and account-mapping problems. For hash imports, account for password changes in Auth0 after the export so users do not arrive with a password that differs from the imported hash. Rollback depends on the previous Auth0 configuration remaining available. You can try restoring that configuration for a test application to observe the return to the Auth0 login flow.

A password set in FoxIDs is not synchronised back to Auth0. A rollback therefore uses the credentials still held by Auth0. Define how users created only in FoxIDs will gain access through Auth0 if rollback is required. For passwordless and federated sign-ins, retain the Auth0 delivery settings and provider connections needed to restore the previous flow. Retire the old integration and remove retained export files only after account access and operational support have been accepted.

Related documentation

• Migration overview
• Upload many users
• Control API user operations
• Login and home realm discovery
• Email provider
• Applications