Rules Environment Best Practices

Rules execute as a series of called JavaScript functions in an instance of an Auth0 serverless Webtask container. As part of this, a specific environment is provided, together with a number of artifacts supplied by both the 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 rule 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 the list, read Can I require: Auth0 Extensibility.

If you require an npm module that is not supported, you can make a request at the Auth0 Support portal or through your Auth0 representative. Auth0 evaluates requests to determine suitability. There is currently no support in Auth0 for the use of npm modules from private repositories. New packages are typically added on a 2-week cycle when requested. Existing packages are rarely removed as this would cause breaking changes in rules. Keep in mind, Auth0 packages and versions are stored on an internal registry and are not in sync with npm.

When using npm modules to access external services, keep API requests to a minimum, avoid excessive calls to paid services, and avoid potential security exposure by limiting what is sent. To learn more, read Performance Best Practices.

When requiring a module in a rule, if the version is not specified, the package manager uses the first version it finds on the internal list. A version may be specified to force the package manager to use a non-default version. This allows rule code to take advantage of fixes or features from the specified version that are not available in the default module version.

Auth0 Rules support environment variables, accessed via the globally available configuration object. Configuration should be treated as read-only and should be used for storing sensitive information, such as credentials or API keys for external service access. This mitigates having security-sensitive values hard-coded in a rule. It can also be used to support Software Development Life Cycle (SDLC) best practice strategies you employ by allowing you to define variables that have tenant-specific values. This mitigates hard-code values in a rule which may change depending upon which tenant is executing it.

Auth0 serverless Webtask containers are provisioned from a pool that's associated with each Auth0 tenant. Each container instance makes available the global object, which can be accessed across all rules that execute within the container instance. The global object acts as a global variable and can be used to define information, or to even define functions, that can be used across all rules (that run in the container) irrespective of the pipeline instance:

global.tokenVerify = global.tokenVerify || function(token, secret) {
      /* The 'jwt.verify' function is synchronous, however wrapping with a promise
      * provides for better error management and integration within the logic
      * flow.
      */
      return new Promise(function(resolve, reject) {
      jwt.verify(
    token,
    secret,{
    clockTolerance: 5},
    function(err, decoded) {
      if (err) {
    reject(err);
      } else {
    resolve(decoded);
      }
      });
    });
    };

The global object can also be used to cache expensive resources, such as an Access Token for a third-party (e.g., logging) API that provides non user-specific functionality or an Access Token to your own API defined in Auth0 and obtained by using Client Credentials flow.

Rules can run more than once when a pipeline is executed, and this depends on the context of operation. For each context in which a rule is run, an existing container instance is either provisioned from the Auth0 tenant pool or may be instantiated anew. For each instantiation of a new Webtask container, the global object is reset. Thus, any declaration within the global object should also include provision for initialization (as shown above), ideally with that declaration being made as early as possible (i.e., in a rule that runs early in the execution order).

The auth0 object is a specially-restricted instance of ManagementClient (defined in the node-auth0 Node.js client library) and provides limited access to the Auth0 Management API. It is primarily used for updating metadata associated with the user object from within a rule.

As well as being restricted (i.e., supporting a limited number of ManagementClient methods for user access only), the Access Token associated with the auth0 object has scopes limited to read:users and update:users. Typically, all of this is sufficient for the majority of operations we recommend being performed from within a rule. However, if you need access to the full range of supported methods, and/or access to additional scope(s), then you will need to employ an alternative means of access to the Management API.

Alternative access to the Management API from within a rule is typically achieved by instantiating an independent instance of the ManagementClient. This will give you access to all current capabilities, including logic like automatic retries on 429 errors as a result of rate limiting policy. In addition, if you only require the default scopes, then you can even initialize the new instance using the Access Token associated with the auth0 object.

Like the context object, the auth0 object contains security-sensitive information, so you should not pass it to any external or third-party service. Further, the Auth0 Management API is both rate limited and subject to latency, so you should be judicious regarding how often calls are made. Read more about context objects on the Rules Execution Best Practices page.

Use the auth0 object (and any other mechanisms for calling the Auth0 Management API) sparingly and use adequate exception and error handling to prevent unexpected interruption of pipeline execution.

• Rules Anatomy Best Practices
• Rules Execution Best Practices
• Rules Security Best Practices
• Rules Testing Best Practices
• Error Handling Best Practices