Introduction

One of the challenges when migrating an application's authentication infrastructure to Auth0 is migrating user information from the existing user database to Auth0.

Auth0 provides the following two user import functions, and this time we will introduce the procedure for "automatic migration".

• Batch import: Migration using a JSON file that defines user information
• Automatic migration: Automatically migrate user information from the existing user database when the user logs in via Auth0

premise

The existing user database environment used in the procedure on this page and the login operation check is as follows.

• Database environment: Use Amazon RDS
  • MySQL version 8.0.28
  • Network connection from Auth0 tenant

*In a real environment, there are cases where it is not possible to directly connect to the database from the Internet. In that case, it is necessary to take measures such as providing an API for database reference.

• Database name: userdb
• Table name: members
• User information stored in the table:

* Hash value by bcrypt

The operation examples on this page are for Auth0-linked web applications. In addition, the information regarding functions and settings described on this page is current as of December 2022.

User migration for automatic migration

The automatic migration function migrates users from the existing user database to Auth0 according to the flow below.

https://auth0.com/docs/manage-users/user-migration#automatic-migrations

Setting overview

To realize user migration by automatic migration, the following settings are required.

• Setting the Custom Database Connection feature
  Define a new Custom Database Connection to enable linkage with the existing user database
• Enabling the automatic migration feature
  Enable the automatic migration function in the defined Custom Database Connection
• Customizing Database Action Scripts
  Define Login and Get User scripts to realize linkage processing with existing user database

Setting Example

1. Setting the Custom Database Connection function

• Click Authentication > Database

• Click + Create DB connection

• Enter an arbitrary connection name in the Name field and click [Create].

• On the Custom Database tab, enable Use my own database

2. Enable automatic migration function

In the Settings tab, enable Import Users to Auth0

3. Customizing Database Action Scripts

• [Custom Database] tab > Database Action Script > [Login] tab, select MySQL (template for MySQL) from [Load Template]

• Edit the template script according to the connection parameters to the existing user database, table information, password hashing algorithm, etc.

function login(email, password, callback) {
　const mysql = require('mysql');
　const bcrypt = require('bcrypt');
　
　const connection = mysql.createConnection({
　　host: ‘データベースのホスト名',
　　user: 'ユーザ名',
　　password: 'パスワード',
　　database: 'データベース名',
　　port: ポート番号
　});
　
　connection.connect();
　
　const query = 'SELECT ID, UserName, Email, Password FROM members WHERE Email = ?';
　
　connection.query(query, [ email ], function(err, results) {
　　if (err) return callback(err);
　　if (results.length === 0) return callback(new WrongUsernameOrPasswordError(email));
　　const user = results[0];
　
　　bcrypt.compare(password, user.Password, function(err, isValid) {
　　　if (err || !isValid) return callback(err || new WrongUsernameOrPasswordError(email));
　
　　　callback(null, {
　　　　user_id: user.ID.toString(),
　　　　//nickname: user.nickame,
　　　　email: user.Email
　　　});
　　});
　});
}


• On the [Get User] tab, select MySQL (Template for MySQL) from [Load Template]

• Edit the template script according to the connection parameters for the existing user database, table information, etc.

function getByEmail(email, callback) {
　const mysql = require('mysql');
　
　const connection = mysql.createConnection({
　　host: 'データベースのホスト名',
　　user: 'ユーザ名',
　　password: 'パスワード',
　　database: 'データベース名',
　　port: ポート番号
　});
　
　connection.connect();
　
　const query = 'SELECT Id, UserName, Email FROM members WHERE Email = ?';
　
　connection.query(query, [ email ], function(err, results) {
　　if (err || results.length === 0) return callback(err || null);
　
　　const user = results[0];
　　callback(null, {
　　　user_id: user.Id.toString(),
　　　//nickname: user.nickname,
　　　email: user.Email
　　});
　});
}

• After editing each script, click [Save And Try] to test the connection

• Enter the user information in the existing user database and click [Try].
  * Enter only the email address for the Get User script

• Confirm the success of the connection test by displaying the following message.

Login confirmation example: login by a user in the existing user database

1. Perform login operation on the web application screen linked with Auth0 and transition to the login screen provided by Auth0

2. Log in with user information in the existing user database

3. Confirm that you were able to log in to the web application with the user information in the existing user database

4. On the Auth0 management screen [User Management] > [Users], check that the users in the existing user database have been imported to Auth0.

in conclusion

By using the automatic migration function, users can be automatically migrated from the existing user database to Auth0 when the user logs in. This function can also be used in the free Auth0 trial environment, so please try it out.
Auth0 has a user migration function in addition to the automatic migration introduced this time. If you are interested in user migration realized by Auth0, please contact us.

reference

• Automatic migrations - Auth0 docs
• Auth0 Configure Automatic Migration from Your Database - Auth0 docs