Custom Database Script Templates
Auth0 provides custom database script templates that you can use when implementing functionality for use with a custom database.
Click Save to Use Scripts
Script templates, including the default templates, are not used until you click Save. 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.
While Auth0 has populated default templates in the Dashboard script editor, you can use the following links to recover the original code and notes once you've made and saved edits.
Script Template Checklist
Use the following checklist to make sure your scripts achieve the results you intend:
user_idon the returned user profile that is consistent for the same user every time. In the migration scenario, this is important because if you set a random
get_userscript, then call
forgot passwordand change the password, the user will get duplicated every time they log in. In the non-migration scenario, if you set a random
user_idyou can end up with duplicate users for every login.
If using a
username, ensure that you aren't returning the same email address for two different users in the
loginscript. Auth0 will produce an error if you do this, but it is better to catch it in the script itself.
app_metadata, call it
metadatain the script. To support backwards compatibility,
metadatain custom DB scripts. If you don't use
metadatain the script, you will get an error where
app_metadatawill work but if you use the API to merge
app_metadatawith a user, it will appear as if all of your metadata was lost.
If using Auth0 to do machine-to-machine to the legacy database, restrict access to that audience with a rule. As with any API that you create, if you create it solely for client credentials, then you will want to restrict access to the API in a rule. By default, Auth0 gives you a token for any API if you authenticate successfully and include the audience. Someone could intercept the redirect to authorize and add the audience to your legacy database API. If you don’t block this in a rule, they will get an access token.
Determine if they are accessing their database directly versus through an API. This item is not a requirement; it is a recommended best practice. A database interface is extremely open. You should add protections between an API endpoint and your database. Most people do not expose their database directly to the internet. Though you can whitelist Auth0 IPs, those IPs are shared in the cloud environment. In general, Auth0 recommends that you protect your database from too many actors directly talking to it. The alternative is to create a simple API endpoint that each script within Auth0 can call. That API can be protected using an access token. You can use the client credentials flow to get the Access Token from within the rules.
If enabling trickle migration, ensure the following:
Loginscript and the
get_userscript both return the same user profile. Because of the two different flows (logging in, or using forgot password), if the
loginscript return different user profiles, then depending on how a user migrates (either by logging in directly, or using the forgot password flow) they will end up with different profile information in Auth0.
user_metadata, use a rule to fetch the metadata if it is missing. The metadata is not migrated until https://YOUR_TENANT.auth0.com/login/callback is called. However, the user credentials are migrated during the post to
usernamepassword/login. This means that if the browser is killed, or computer dies or something on a user after they have posted to
usernamepassword/login, but before login/callback, then they will have a user in the Auth0 database, but their app and user metadata are lost. It is really important, therefore, to create a rule that looks a lot like your
get_userscript to fetch the profile if app and user metadata are blank. This should only execute once per user at most (and usually never).
Use a rule to mark users as migrated. This is not a hard requirement, but it does protect against one scenario in which a user changes their email address, then changes it back to the original email address. A rule should call out to the legacy database to mark the user as being migrated in the original database so that
get_usercan return false.