Best Practices for Database Action Scripts

Secure access to your external user store

When you use a custom database connection, you need to provide an interface to your user store so Auth0 can connect to it. If you do this by making your user store broadly accessible via the internet, you incur significant risks. For example, interfaces for SQL and other databases expose significant functionality, and making them generally available violates the principle of least privilege.

Provide access with a protected API

We recommend providing access with an API that has discrete number of protected endpoints to perform only the user management functionality required for the custom database connection, like read user and change password. Protecting this API with use of an allows you to use the client credentials grant flow from within an action script. You can subsequently cache the token for re-use within the global object to improve performance. If your external user store has an API available, or if you implement one yourself, you can register the API through Auth0, and create an Action to restrict access from end users. By default, Auth0 can give you a token for any API if you authenticate successfully and include the appropriate . Restricting access to your user store’s API by restricting access token allocation prevents unauthorized usage by only granting access using specific client credentials. This mitigates a number of attack vector scenarios, such as a bad actor intercepting redirects to /authorize and adding the audience to the API. If your external user store does not have an API available and implementing one is not feasible, you can still write your action scripts to communicate with it directly.

Restrict network access

We recommend restricting access to your external user store with an IP allowlist including Auth0’s outbound IP addresses to allow inbound traffic from Auth0. Because Auth0’s outbound IP addresses are shared between all Auth0 tenants in the given region, we recommend against using such an allowlist as the sole method of securing access to your user store. Instead, use an allowlist as one of several security measures.

Time out async and external calls

If you call an external service or API within your action script, set the function to time out after a reasonable duration, and return an error if the external service or API cannot be reached.

Promise object example

This example uses the built-in JavaScript fetch method, which gets a resource from a network then returns a Promise object, written using promise chains.

function login(userNameOrEmail, password, callback) {
	const hashedPassword = hash(password);
	const apiEndpoint = 'https://example.com/api/authenticate';
	const options = {
		method: 'POST',
		body: {
			email: userNameOrEmail,
			password: hashedPassword
		}
	};

	fetch(apiEndpoint, options) 
		.then((response) => {
			if (!response.ok) {
				return callback(new Error(`HTTP error! Status: ${response.status}`));
			}

			return response.json();
		})
		.then((response) => {
			if (response.err) {
				return callback(new Error(`Error authenticating user: ${err}`));
			}

			let profile = {
				email: response.profileData.email,
				username: response.profileData.username
			};

			return callback(null, profile);
		})
		.catch((err) => {
			return callback(new Error(`An error occurred: ${err}`));
		});
  }

Async function example

This example uses the built-in JavaScript fetch method, which gets a resource from a network then returns a Promise object, written using async functions.

async function login(userNameOrEmail, password, callback) {
	const hashedPassword = hash(password);
	const apiEndpoint = 'https://example.com/api/authenticate';
	const options = {
		method: 'POST',
		body: {
			email: userNameOrEmail,
			password: hashedPassword
		}
	};

	const response = await fetch(apiEndpoint, options);

	if (!response.ok) {
		return callback(new Error(`HTTP error! Status: ${response.status}`));
	}

	const result = response.json();

	if (result.err) {
		return callback(new Error(`Error authenticating user: ${err}`));
	}

	let profile = {
		email: response.profileData.email,
		username: response.profileData.username
	};

	return callback(null, profile);
}

You can return errors from custom database action scripts by passing them to the callback function. We recommend using descriptive error messages to help with troubleshooting and debugging.

Avoid anonymous functions

You can implement action scripts as anonymous functions, but we recommend using function names because anonymous functions can make it difficult to interpret the call stack when debugging error conditions.

Retrieve identity provider tokens

If the user object returns the access_token and refresh_token properties, Auth0 handles them differently from other types of user information. Auth0 stores them in the user object’s identities property:

{
	"email": "you@example.com",
	"updated_at": "2019-03-15T15:56:44.577Z",
	"user_id": "auth0|some_unique_id",
	"nickname": "a_nick_name",
	"identities": [ 
		{
			"user_id": "some_unique_id",
			"access_token": "e1b5.................92ba",
			"refresh_token": "a90c.................620b",
			"provider": "auth0", 
			"connection": "custom_db_name",
			"isSocial": false 
		}
  ], 
  "created_at": "2019-03-15T15:56:44.577Z",
  "last_ip": "192.168.1.1",
  "last_login": "2019-03-15T15:56:44.576Z",
  "logins_count": 3
}

To retrieve either of these properties with the Auth0 , include the read:user_idp_tokens scope when requesting an Access Token.

Add Login

Provision Users

Best Practices for Database Action Scripts

Secure access to your external user store

Provide access with a protected API

Restrict network access

Time out async and external calls

Avoid anonymous functions

Retrieve identity provider tokens

​Secure access to your external user store

​Provide access with a protected API

​Restrict network access

​Time out async and external calls

​Avoid anonymous functions

​Retrieve identity provider tokens

Secure access to your external user store

Provide access with a protected API

Restrict network access

Time out async and external calls

Avoid anonymous functions

Retrieve identity provider tokens