Docs

Login Script Templates

The Login script implements the function executed each time a user is required to authenticate. We recommend naming this function login. The login function is typically used during the Universal Login workflow, but is also applicable in other authentication flow scenarios (such as Resource Owner Password Grant). The script is required for both legacy authentication and for automatic migration.

The login function should be defined as follows:

Parameter Description
userNameOrEmail The identification credential for the user typically either the email address for the user or the name associated with the user. With default out-of-box Universal Login, support for the use of username during login is available only if the Requires Username setting is enabled for the database connection.
password Passed to the login script in plain text. Do not store it or transport it anywhere in its vanilla form. Use bcrypt as described below.
callback Executed with up to two parameters. The first parameter is an indication of status: a null first parameter with a corresponding second parameter indicates that the operation executed successfully, while a non null first parameter value indicates that some error condition occurred. If the first parameter is null then the second parameter is the profile for the user in JSON format. If the first parameter is non null then the second parameter can be omitted. The second parameter is the profile for the user. This should be supplied as a JSON object in normalized user profile form. See the example below.

Best practice

When indicating an error condition we recommend using the Error object to provide Auth0 with a clear indication of the error condition. For example, callback(new Error(“an error message”)).

`bcrypt` hash encryption

The password credential for the user is passed to the login script in plain text so care must be taken regarding its use. You should refrain from logging, storing, or transporting the password credential anywhere in its vanilla form. Instead, use something similar to the following example, which uses the bcrypt algorithm to perform cryptographic hash encryption:

callback profile parameter example

The second parameter provided to the callback function should be the profile for the user. This should be supplied as a JSON object in normalized user profile form.

The profile returned by the login script for a user should be consistent with the profile returned in the getUser script, and vice-versa.

Additionally, you can also provide metadata for a user as part of the user profile returned. The following is an example of the profile object that can be returned for a user.

Parameter Description
username If a custom database connection type has Requires Username as an enabled setting then the profile returned for the user must include a username. If the setting is not enabled then username is optional and can be omitted.
user_id The user_id value must be specified and provides the unique identifier for a user. For the auth0 strategy, the strategy used to define a custom database connection, Auth0 automatically decorates whatever user_id value is supplied by prefixing the text auth0| in order to create the user_id in the root of the normalized user profile. The user_id value supplied will appear in it’s undecorated form in the identities array associated with the user profile in Auth0. The user_id value specified must be unique across all database connections defined in an Auth0 tenant. Failure to observe this will result in user identifier collision which will lead to unpredictable operation. One way to avoid this is to explicitly prefix the supplied user_id with the name of, or pseudonym for, the connection (omitting any whitespace). The user_id value must also be consistent for any given user; the value returned by the Login script must also be consistent with the value returned by the Get User script, and vice-versa. Failure to observe this requirement can lead to duplicate Auth0 user profiles for a user, duplicate identities for any user migrated via automatic migration, and/or unpredictable results when it comes to user operations.
email An email value should also be specified. While an email address is not mandatory for a user, much of Auth0 out-of-box functionality such as password reset, requires that a user has a valid and verified email address. Email addresses should be returned consistently for all scripts and should also be unique within the context of a single custom database connection (for automatic migration scenarios). Failure to observe either of these requirements will typically lead to unpredictable results when it comes to user operation.

If you are providing app_metadata as part of the user profile then you should refer to this as metadata in the profile object returned. Failure to do this will result in a loss of the metadata if any modifications are made to the users’ app_metadata in the future.

Best Practice

While a user does not need to use an email address to login, it’s recommended best practice that they have an email address defined against their user profile. This ensures that Auth0 out-of-box functionality works as designed.

For a legacy authentication scenario, you can also enable the Sync user profile at each login option in the settings for a custom database connection. This allows attribute updatess in the Auth0 user profile each time a login for the user occurs for attributes that would otherwise not be available for update via the Auth0 Management API. For legacy authentication scenarios there are a number of root profile attributes which cannot be updated directly via the Management API.

In order to update name, nickname, given_name, family_name, and/or picture attributes associated with the root of the normalized user profile, you must configure user profile sync so that user attributes will be updated from the identity provider. Auth0 does not support update of these attributes for a custom database connection used for legacy authentication.

Language-specific script examples

Auth0 provides sample scripts for use with the following languages/technologies:

JavaScript

ASP.NET Membership Provider (MVC3 - Universal Providers)

ASP.NET Membership Provider (MVC4 - Simple Membership)

MongoDB

MySQL

Oracle

PostgreSQL

SQL Server

Windows Azure SQL Database

Request with Basic Auth

Stormpath

Keep reading