Create Custom Database Connections

If you have your own user database, you can use it as an identity provider in Auth0 to authenticate users. In this process, you will create the custom database connection, create database action scripts, and add configuration parameters.

Auth0 allows you to create connections and scripts for most of the commonly-used databases, including:

• ASP.NET Membership Provider

• MongoDB

• MySQL

• PostgreSQL

• SQLServer

• Windows Azure SQL Database

• Web services accessed via Basic Auth

You can connect to any kind of database or web service with a properly-configured custom script. Note that input sanitization must be completed on the customer end; Auth0 does not sanitize or validate any username/password combination passed by a custom database. Custom Database scripts are subject to Auth0's Rate Limit Policy.

1. Navigate to Auth0 Dashboard > Authentication > Database, and select Create DB Connection.

   

2. Configure the connection's settings, and click Create:

   Parameter	Definition
   Name	The name of the connection. The name must start and end with an alphanumeric character, contain only alphanumeric characters and dashes, and not exceed 35 characters.
   Requires Username	Forces users to provide a username and email address during registration.
   Username Length	Sets the minimum and maximum length for a username.
   Disable Sign Ups	Prevents signups to your application. You will still be able to create users with your API credentials or via the Auth0 Dashboard.

   Once Auth0 creates your connection, you'll have the following views (in addition to the Settings view):

   • Attributes

   • Authentication Methods

   • Custom Database

   • Applications

3. Select the Custom Database view, and enable the Use my own database switch.

   

Toggling the Use my own database switch enables the Database Action Scripts area where you will create scripts to configure how authentication works when using your database. You can write your database action scripts, or you can select a template from the Templates dropdown and modifying it as necessary.

You must configure a login script; additional scripts for user functionality are optional.

The available database action scripts are:

To learn more about the scripts, read Custom Database Action Script Templates and Custom Database Action Script Execution Best Practices.

The following steps use an example for a MySQL database login script

1. After toggling the Use my own database switch, the Database Action Scripts area is enabled. Make sure you are on the Login tab.

2. Use the Templates dropdown to select the MySQL database script template.

   function login(email, password, callback) {
     var bcrypt = require('bcrypt');
     var mysql = require('mysql');
     var connection = mysql.createConnection({
       host: 'localhost',
       user: 'me',
       password: 'secret',
       database: 'mydb'
     });
     connection.connect();
     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(new WrongUsernameOrPasswordError(email));
       var user = results[0];
       bcrypt.compare(password, user.password, function (err, isValid) {
         if (err) {
           callback(err);
         } else if (!isValid) {
           callback(new WrongUsernameOrPasswordError(email));
         } else {
           callback(null, {
             // This prefix (replace with your own custom DB name)
             // ensure uniqueness across different custom DBs if there's the
             // possibility of collisions (e.g. if the user ID is an email address or an integer)
             id: 'MyConnection1|' + user.id.toString(),
             nickname: user.nickname,
             email: user.email
           });
         }
       });
     });
   }

   Was this helpful?

   Yes /No
   The above script connects to a MySQL database and executes a query to retrieve the first user with email == user.email. With the bcrypt.compareSync method, it then validates that the passwords match, and if successful, returns an object containing the user profile information including id, nickname, and email. This script assumes that you have a users table containing these columns. The id returned by Login script is used to construct the user ID attribute of the user profile.

3. Click Save and Try.

4. In the pop-up modal, enter your email and password and click Try. This provides a dropdown to select from a list of available runtimes, with your current runtime on top.

   

Script templates are not used by Auth0 until you click Save or Try. This is true even if you only modify one script and haven't made changes to any others. You must click Save at least once for all the scripts to be in place.

If you use custom database connections in conjunction with Organizations, you can use the context parameter in the script signature to make Organization details like id, name, and metadata available to your custom database action scripts. Organization data is passed in the context object when the associated action happens in the context of an organization; for example, when a user authenticates on an organization’s login prompt, the login action script is passed. To learn more, read Database Connections.

1. Navigate to Auth0 Dashboard > Authentication > Database.

2. Select your database connection.

3. Under the Custom Database tab, find Context objects in database scripts and select Enable.

   
   This feature cannot be disabled once toggled.

Once the context object is enabled in Dashboard, you can add a `context` object to your custom database action scripts, inserted directly preceding the callback parameter. When events are triggered with Organization context, the corresponding data is made available to your custom database action scripts in the format below:

{
    "organization": {
        "display_name": "My Organization",
        "id": "org_XXXXXX",
        "metadata": {
            "example": "value"
        },
        "name": "my-organization"
    }
}

{
    "organization": {
        "display_name": "My Organization",
        "id": "org_XXXXXX",
        "metadata": {
            "example": "value"
        },
        "name": "my-organization"
    }
}

{
    "organization": {
        "display_name": "My Organization",
        "id": "org_XXXXXX",
        "metadata": {
            "example": "value"
        },
        "name": "my-organization"
    }
}

{
    "organization": {
        "display_name": "My Organization",
        "id": "org_XXXXXX",
        "metadata": {
            "example": "value"
        },
        "name": "my-organization"
    }
}

{
    "organization": {
        "display_name": "My Organization",
        "id": "org_XXXXXX",
        "metadata": {
            "example": "value"
        },
        "name": "my-organization"
    }
}

You can store parameters, like the credentials required to connect to your database, in the Settings section below the script editor. These will be available for all of your scripts, and you can access the parameter values using the configuration object in your database action scripts (i.e., configuration.MYSQL_PASSWORD).

Use the added parameters in your scripts to configure the connection. For example, you might add the following to the MySQL Login script:

function login (username, password, callback) {
  var mysql = require('mysql');
  var connection = mysql.createConnection({
    host     : configuration.MYSQL_HOST,
    user     : 'me',
    password : configuration.MYSQL_PASSWORD,
    database : 'mydb'
  });
}

• Custom Database Connection and Action Script Best Practices
• Troubleshoot Custom Databases
• Import and Export Users