# Migrate user store

Migrating to Mosaic from another authentication provider is designed to be seamless and secure. Whether you're transitioning from legacy systems or established identity providers like Okta, Auth0, Azure AD, or AWS Cognito, Mosaic supports flexible migration strategies that minimize disruption for your users.

## Choose a migration path

There are two primary ways to migrate users to Mosaic, depending on your requirements:

- **Just-In-Time (JIT) migration**: Migrate users gradually as they authenticate. This approach allows for a smooth transition without requiring downtime or bulk data exports.
- **Bulk import**: Import users into Mosaic before they sign in.


## Just-in-time (JIT) migration

When a user logs in, Mosaic validates their credentials against your existing IDP and automatically creates or updates their Mosaic profile.

Mosaic supports multiple authentication methods for JIT migration:

| Method | Description |
|  --- | --- |
| Password authentication | Validates username/password credentials directly against your existing IDP using ROPC (Resource Owner Password Credentials). |
| Email OTP authentication | Sends and verifies email one-time passcodes through your existing IDP. |
| SMS OTP authentication | Sends and verifies SMS one-time passcodes through your existing IDP. |
| TOTP authentication | Validates time-based one-time passcodes generated in the user's authenticator app against your existing IDP. |
| OIDC redirect | Redirects users to your existing IDP for authentication using the OIDC Authorization Code flow. |


Mosaic's Integration Hub provides pre-built connectors for major identity providers. Journeys expose only the authentication methods an IDP supports.

| Provider | OIDC | Password | Email OTP | SMS OTP | TOTP |
|  --- | --- | --- | --- | --- | --- |
| Okta | [✓](/guides/orchestration/journeys/authenticate_okta_oidc) | [✓](/guides/orchestration/journeys/authenticate_okta_password) | – | – | [✓](/guides/orchestration/journeys/authenticate_okta_totp) |
| Auth0 | [✓](/guides/orchestration/journeys/authenticate_auth0_oidc) | [✓](/guides/orchestration/journeys/authenticate_auth0_password) | – | – | – |
| AWS Cognito | [✓](/guides/orchestration/journeys/authenticate_cognito_oidc) | [✓](/guides/orchestration/journeys/authenticate_cognito_password) | [✓](/guides/orchestration/journeys/authenticate_cognito_otp_generate) | [✓](/guides/orchestration/journeys/authenticate_cognito_otp_generate) | – |
| Microsoft Entra ID | [✓](/guides/orchestration/journeys/authenticate_azuread_oidc) | [✓](/guides/orchestration/journeys/authenticate_azure_ad_password) | – | – | – |
| Keycloak | [✓](/guides/orchestration/journeys/authenticate_keycloak_oidc) | [✓](/guides/orchestration/journeys/authenticate_keycloak_password) | – | – | [✓](/guides/orchestration/journeys/authenticate_keycloak_totp) |
| OneLogin | [✓](/guides/orchestration/journeys/authenticate_onelogin_oidc) | [✓](/guides/orchestration/journeys/authenticate_onelogin_password) | – | – | – |
| Ping Identity | [✓](/guides/orchestration/journeys/authenticate_pingone_oidc) | [✓](/guides/orchestration/journeys/authenticate_pingone_password) | – | – | – |
| Google | [✓](/guides/orchestration/journeys/authenticate_google_oidc) | – | – | – | – |
| Meta (Facebook) | [✓](/guides/orchestration/journeys/authenticate_meta_oidc) | – | – | – | – |
| Apple | [✓](/guides/orchestration/journeys/authenticate_apple_oidc) | – | – | – | – |


To implement this path, see [Set up JIT migration](/guides/platform/migration_steps).

## Bulk import

Bulk import takes the data in your existing user store, such as user profiles and password hashes, and imports it into Mosaic in one operation. Users don't need to authenticate for their data to be in Mosaic.

Use bulk import when you need users in Mosaic regardless of whether they log in. For example:

- **After a JIT migration period**: a typical migration starts with JIT, then bulk imports the remaining users who haven't logged in, so you can retire the existing IDP.
- **Before go-live**: you want all users to exist in Mosaic before you switch authentication over, so you can manage them from the Admin Portal from day one.


Bulk import is create-only: if a user already exists in Mosaic, that record is not updated.

Bulk import does not include:

- Roles, groups, or other entitlements
- Authenticators, devices, or sessions
- Organization membership (B2B)


To implement this path, see [Set up bulk import](/guides/platform/bulk_user_migration).

## Planning your migration

Consider the following when planning your migration:

- **Path**: Use JIT when users should migrate at login against a live IDP. Use bulk when you need users in Mosaic before they authenticate. Many migrations combine both: JIT first, then bulk import for users who haven't logged in.
- **Timeline**: JIT migration happens as users log in. Plan for a period when both systems may be active. Bulk import creates users as soon as the run processes them.
- **Schema**: Decide which identifiers and attributes to keep, and add [custom user fields](/guides/user/manage_user_schema) in Mosaic before you import or map journey outputs.
- **Authenticator registration**: Decide whether to prompt users to register Mosaic authenticators immediately or during later logins.
- **Roles and groups**: Assign roles and groups in Mosaic after users exist. Neither path imports them from the source.
- **Rollback strategy**: Keep the source IDP available during the transition so you can continue to authenticate users if needed.