Authenticate Database Users with Username and Password

Applications often rely on user databases for authentication. Auth0 allows you to easily connect to these repositories and reuse them as identity providers, while preserving user credentials, and adding the many features Auth0 provides.

In this tutorial, you will be guided through a series of steps to connect your user database to Auth0.

Create a database connection

Log into Auth0, and select the Connections > Database menu option. Click the New Database Connection button and provide a name for the database, or select a database you have created previously.

Customize the database connection

Auth0 ships with multiple templates to connect to commonly used database systems like MySQL, SQL Server, SQL Azure, MongoDb, Couchbase, Postgres, ASP.NET Membership, and others.

In this tutorial, you will be using MySQL.

Click Custom Database and enable Use my own database.

In the Templates drop-down, select MySQL.

The following code is generated for you in the connection editor:

function login (email, password, callback) {
  var connection = mysql({
    host     : 'localhost',
    user     : 'me',
    password : 'secret',
    database : 'mydb'


  var query = "SELECT id, nickname, email, password " +
             "FROM users WHERE email = ?";

  connection.query(query, [email], function (err, results) {
    if (err) return callback(err);
    if (results.length === 0) return callback();
    var user = results[0];

    if (!bcrypt.compareSync(password, user.password)) {
      return callback();

    callback(null,   {
      nickname:    user.nickname,



This script connects to a MySQL database and executes a query to retrieve the first user with email == With the bcrypt.compareSync method, it then validates that the passwords match, and if successful, returns an object containing the user profile information id, nickname, and email. This script assumes that you have a users table containing these columns. You can tweak this script in the editor to adjust it to your own requirements.


In the Settings section at the bottom of the page, you can securely store the credentials needed to connect to your database.

In the connection script, refer to these parameters as: configuration.PARAMETER_NAME. For example, you could enter:

function login (username, password, callback) {
  var connection = mysql({
    host     : 'localhost',
    user     : 'me',
    password : configuration.MYSQL_PASSWORD,
    database : 'mydb'

Debug and troubleshoot

Test the script using the TRY button. If your settings are correct you should see the resulting profile:

Auth0 Login Widget

After you have enabled the database connection, Auth0's widget will automatically change its appearance to allow users to enter their username and password. Once entered, this data is passed into your script.

How it works

The script runs in a JavaScript sandbox where you can use the full power of the JavaScript language and selected libraries. The current API supports:




To return an error, call the callback with an error as the first parameter:


There are three different errors you can return from a DB Connection:

  • new WrongUsernameOrPasswordError(<email or user_id>, <message>): For when you know who the user is and you want to keep track of a wrong password.
  • new ValidationError(<error code>, <message>): A generic error with an error code.
  • new Error(<message>): Simple errors (no error code).


callback(new ValidationError('email-too-long', 'Email is too long.'));

NOTE: Do you require support for other libraries? Contact us at