Implementing debugging best practices in Auth0 ensures efficient troubleshooting and code maintenance. These practices include utilizing real-time logging, adding line comments, managing debug logging environments, and performing static analysis on custom code.

• Auth0
• Debugging
• Best Practices

How is rule debugging performed?

NOTE: Actions, Rules, Hooks, Extensions, and Database Scripts generate the consoleOut property log output within the Auth0 platform. Auth0 recommends using the consoleOut property for testing and debugging purposes only. Do not log personal data or other sensitive data into the web console, or the log output includes such data.

Administrators typically debug a rule during runtime via console logging by using the console.log facility. Review the console.log() in MDN Web Docs documentation for more information. Interactive debugging of a rule remains unavailable within the Auth0 platform.

Add Line Comments for Code Clarity

Adding sufficient line (//) or block (/* */) comments to a rule, particularly around non-obvious functionality, assists with code debugging and code understanding. This practice proves invaluable when the initial implementer of a rule differs from the person maintaining it.

How are Actions Real-time Logs utilized?

Auth0 hides console log output by default during normal execution. However, administrators can use the Actions Real-time Logs to display all console logs in real-time for implemented extensibility in an Auth0 tenant. The real-time console log display includes console.log output, console.error output, and console.exception output.

Enable and Disable Debug Logging Conditionally

In a production environment, continuous debug logging remains undesirable due to performance considerations associated with rules. Review the Auth0 Performance Best Practices documentation for more information. However, in a development or testing environment, enabling debug logging on a continuous basis proves beneficial. Excessive debug logging creates substantial noise, making problem identification difficult.

Modifying a rule to enable or disable debug logging dependent on the environment introduces errors. Instead, leverage the environment configuration object to implement conditional processing. Review the following code snippet for an example of conditional processing.

function NPClaims(user, context, callback) {
    /*
     * This rule (https://auth0.com/docs/rules) is used to derive
     * effective claims associated with the Normalized User Profile:
     *   https://auth0.com/docs/user-profile/normalized/auth0
     */
    var LOG_TAG = '[NORMALIZED_PROFILE_CLAIMS]: ';
    var DEBUG = configuration.DEBUG ? console.log : function () {};
    DEBUG(LOG_TAG, "identities=", user.identities);
    user.user_metadata = user.user_metadata || {};

    //
    user.family_name =
      user.family_name ||
      user.identities.filter(function(identity) {
        /* Filter out identities which do not have anything synonymous with
         * Family Name
         */
        return(
          identity.profileData &&
          identity.profileData.family_name);
      }).map(function(identity) {
        return identity.profileData.family_name;
      })[0];
    DEBUG(LOG_TAG, "Computed user.family_name as '", user.family_name, "'");
      .
      .

    //
    return callback(null, user, context);
  }

The example above creates a DEBUG environment configuration variable, which accepts true or false depending on the execution environment (e.g., production, testing, development). The setting of this variable determines when debug logging occurs. Furthermore, creating a DEBUGLEVEL environment configuration variable controls the debugging log level (e.g., verbose, medium, sparse).

The example above also demonstrates the declaration of a named function. Providing a function name using a compact and unique naming convention assists with diagnostic analysis. Anonymous functions complicate debugging situations when interpreting the call-stack generated by an exceptional error condition. Providing a unique function name addresses this issue. Review the Auth0 Error Handling Best Practices documentation for more information.

Perform Static Analysis Using Third-Party Tools

The rule editor in the Auth0 Dashboard provides rudimentary syntax checking and analysis of rule semantics. However, the editor lacks provision for complex static code analysis, such as overwrite detection, loop detection, or vulnerability detection. To address this, leverage third-party static analysis tooling in conjunction with rule testing as part of the deployment automation process. Examples of these tools include JSHint, SonarJS, or Coverity. These are examples only, and administrators should use a tool that best fits organizational guidelines for these types of tools. Review the Deployment Best Practices documentation for more information.