Custom Database Action Script Environment Best Practices

Action scripts execute as a series of called JavaScript functions in an instance of a serverless Webtask container. As part of this, a specific environment is provided, together with a number of artifacts supplied by both the Webtask container and the Auth0 authentication server (your Auth0 tenant) itself.

Auth0 serverless Webtask containers can make use of a wide range of npm modules; npm modules not only reduce the overall size of action script code implementation, but also provide access to a wide range of pre-built functionality.

By default, a large list of publicly-available npm modules are supported out-of-the-box. This list has been compiled and vetted for any potential security concerns. To see which npm modules are supported, read Can I require: Auth0 Extensibility.

If you require an npm module that is not supported out-of-the-box, then you can make a request via the Auth0 Extensibility portal or through your Auth0 representative. Auth0 will evaluate your request to determine suitability, if you need to escalate an unresolved request open a support ticket via the Auth0 support portal. There is currently no support in Auth0 for the use of npm modules from private repositories.

Auth0 action scripts support the notion of environment variables, accessed via what is defined as the globally-available configuration object. The configuration object should be treated as read-only and should be used for storing sensitive information, such as credentials or API keys for accessing external identity stores. This mitigates having security-sensitive values hardcoded in an action script.

The configuration object can also be used to support whatever Software Development Life Cycle (SDLC) best practice strategies you employ, such as setting up multiple environments, by allowing you to define variables that have tenant-specific values. This mitigates hardcoded values in an action script, which may change depending upon which tenant is executing it.

Auth0 serverless Webtask containers are provisioned from a pool that is associated with each Auth0 tenant. Each container instance makes available a global object, which can be accessed across all action scripts that execute within it (the container instance). The global object acts as a global variable that is unique to the container and that can be used to define information—or even functions—that can be used across all action scripts that run in it (the container instance).

This means that the global object can be used to cache expensive resources, as long as those resources are not user-specific. For example, an Access Token for a third-party (e.g., logging) API that provides non user-specific functionality could be stored. Or it could be used to store an Access Token to your own non user-specific API defined in Auth0 and obtained via use of the Client Credentials flow.

Each time a Webtask container is recycled, or for each instantiation of a new Webtask container, the global object it defines is reset. Thus, any declaration of assignment within the global object associated with a container should also include provision for initialization. To provide performance flexibility, serverless Webtask containers are provisioned in Auth0 on an ad-hoc basis and are also subject to various recycle policies. In general, we recommend that you do not consider the life of a global object to be anything more than 20 minutes.

• Make sure that your database has the appropriate fields to store user profiles attributes, such as id, nickname, email, and password. To learn more about Auth0's user profile schema and expected fields, read Normalized User Profiles. To learn how to update user profiles, read Update User Profiles Using Your Database.

• You can use return errors resulting from your custom database connection for troubleshooting purposes.

• 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 the 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). To learn more about user IDs, read Identify Users.

• Latency will be greater compared to Auth0-hosted user stores.

• The database or service must be reachable from the Auth0 servers. You will need to configure inbound connections if your store is behind a firewall.

The runtime version for custom Database scripts is defined at Dashboard > Settings > Advanced within the Extensibility section.

Follow these steps to test a single custom database script on a specific runtime version:

1. Navigate to Authentication > Database.

2. Select the Database connection where you have defined a custom script.

3. From within the selected database connection's page, select the Custom Database tab.

4. Scroll to Database Action Scripts section of the page.

5. Select the specific script you want to verify (eg. Login, Create etc) on the respective tab.

6. Select Save and Try. This loads a modal with specific test parameters and sample context details. Update as needed.

7. Select Try from the modal to open a dropdown selector for a specific Node version.

8. The test would trigger upon selecting the desired Node version and results would show up in a message on the same screen.

• Custom Database Action Script Execution Best Practices
• Error Handling Best Practices
• Debugging Best Practices
• Deployment Best Practices
• Custom Database Connection Security Best Practices