Understanding Import Mode for Custom Database Connections

Knowledge Articles
1

Overview

This article explains the difference between enabling (ON ) and disabling (OFF ) the Import Users to Auth0 setting for a custom database connection. Understanding this setting is crucial for developers managing user migration and authentication workflows. This feature, often referred to as “Import Mode,” dictates how Auth0 interacts with an external user database during the login process.

Applies To

  • User Imports
  • Import Mode
  • Import Users to Auth0

Solution

The mode chosen determines how user credentials are managed and which scripts are required for the integration:

Import Mode Off

In this configuration, the external database remains the sole source of truth for user identity. Auth0 does not store user credentials.

  • When a user authenticates, Auth0 executes the Login script. This script validates the user’s credentials directly against the database.
  • Required Scripts: As the database handles all identity operations, Auth0 requires a complete set of scripts to delegate these actions:
    • Login: To authenticate users.
    • Get User: To fetch a user profile.
    • Change Password: To process password changes in the database.
    • Delete: To remove users from the database.
    • Verify: To manage email verification status in the database.

Import Mode On

This mode is used to migrate users from an external database into the Auth0 user store.

  • On a user’s first login, Auth0 executes the Login script to validate credentials against the database. Upon success, the user’s profile and a newly hashed password version are created and stored within Auth0.
  • The user is authenticated directly against the record stored in Auth0 for subsequent logins. The external database is not called for that user again.
  • “Import Mode On” aims to facilitate a one-time migration of each user into Auth0. Therefore, only two scripts are necessary:
    • The Login Script: This is required to validate the user against the legacy system and initiate the migration into Auth0.
    • The Get User Script: This allows user profiles to be looked up from the external database before their first login.

Once a user is migrated, all other identity functions (password changes, deletions, etc.) are handled directly by the Auth0 platform. The scripts for these functions are no longer needed for migrated users.