Create an Auth0 database connection
If you have your own user database, you can use it as an identity provider in Auth0 to authenticate users. In this tutorial, we'll show you how to create and configure a custom database connection using the Auth0 dashboard.
Step 1: Create and configure a custom database connection
The first thing you will do is create a database connection in Auth0:
Log in to the Dashboard and navigate to Connections > Database.
Click + Create DB Connection.
Configure the connection's settings as requested.
|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.|
- Click Create to proceed.
Once Auth0 creates your connection, you'll have the following tabs (in addition to the Settings tab):
- Password Policy
- Custom Database
- Try Connection
Switch over to the Custom Database tab.
Toggle the Use my own database switch to enable this feature.
Step 2: Create database action scripts
Toggling the Use my own database switch enables the Database Action Scripts area. This area is where you will create scripts to configure how authentication works when using your database.
You must configure a login script; additional scripts for user functionality, such as password resets, are optional.
You can write your database action scripts, or you can begin by selecting a template from the Templates dropdown and modifying it as necessary.
The available database actions are as follows.
|Executes each time a user attempts to log in.||
|Create||Executes when a user signs up.||
|Verify||Executes after a user follows the verification link.|
|Change Password||Executes when a user clicks on the confirmation link after a reset password request.||
|Get User||Retrieves a user profile from your database without authenticating the user.|
|Delete||Executes when a user is deleted from the API or Auth0 dashboard.||
Create the Login script
The Login script will run each time a user attempts to log in. To create your script, you can:
- Write your Login script
- Select a template from the Templates dropdown.
For example, the MySQL Login template is as follows:
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.
Be sure to Save your changes. Note that clicking Try to test your script will also save your script.
Heads up 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.
User Metadata and Custom Databases
Depending on your custom database script, you may return a user profile to Auth0 apps. This profile includes the user metadata fields. The app_metadata field(s) should be referred to as metadata in scripts for custom databases.
Identity Provider (IdP) Tokens
user object returns the
refresh_token properties, Auth0 handles these slightly differently from other pieces of user information. They will be stored in the
identities property, and retrieving them using the API, therefore, requires an additional scope:
Step 3: 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 to 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.
Use the added parameters in your scripts to configure the connection. For example, you might add the following the MySQL Login template:
In this article, we showed you how to configure your database for use with Auth0 as an identity provider. You:
- Created an Auth0 database connection
- Created database action scripts
- Added configuration parameters
At this point, your database is now ready to act as an Auth0 identity provider.