Docs

Create Custom Database Connections

Feature availability

Only Enterprise subscription plans include the ability to use a custom database for authentication requests. For more info, see Auth0 pricing plans.

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.

Make sure that your database has the appropriate fields to store user profiles attributes, such as id, nickname, email, and password. See Normalized User Profile for details on Auth0's user profile schema and the expected fields. Also, see Update User Profile Using Your Database for more information.

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

  • ASP.NET Membership Provider
  • MongoDB
  • MySQL
  • Oracle
  • 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.

Network firewall

If you are behind a firewall, this feature may require whitelisting of the appropriate Auth0 IP addresses to work properly.

Create the connection in the Dashboard

  1. Log in to the Dashboard and navigate to Connections > Database.

  2. Click + Create DB Connection.

    Database connections

  3. Configure the connection's settings as requested.

    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 sign-ups to your application. You will still be able to create users with your API credentials or via the Dashboard, however.
  4. Click Create.

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

    • Password Policy
    • Custom Database
    • Applications
    • Try Connection
  5. Select the Custom Database tab.

  6. Toggle the Use my own database switch to enable the feature.

    Custom database tab

Create database action scripts

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:

Name Description Parameters
Login
Required
Executes each time a user attempts to log in. email, password
Create Executes when a user signs up. user.email, user.password
Verify Executes after a user follows the verification link. email
Change Password Executes when a user clicks on the confirmation link after a reset password request. email, newPassword
Get User Retrieves a user profile from your database without authenticating the user. email
Delete Executes when a user is deleted from the API or Auth0 dashboard. id
Change Email Executes when a change in the email address, or the email address status, for a user occurs. email, newEmail, verified, callback

See Custom Database Action Script Templates and Database action script best practices for details on all the scripts.

Create a Login script

Avoid User ID Collisions with Multiple Databases

The id (or alternatively user_id) property in the returned user profile will be used by Auth0 to identify the user.

If you are using multiple custom database connections, then id value must be unique across all the custom database connections to avoid user ID collisions. Our recommendation is to prefix the value of id with the connection name (omitting any whitespace). See Identify Users for more information on user IDs.

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.

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.

  1. Click Save.
  2. Click Try to test the script. (This step will also save your script.)

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.

Add configuration parameters

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 them using the global configuration object.

You can access parameter values using the configuration object in your database action scripts (i.e., configuration.MYSQL_PASSWORD).

Custom database settings

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

Keep reading