Performance Best Practices

Rules execute as part of a pipeline where artifacts for authenticity are generated, as described in Custom Database Anatomy Best Practices. As such, an enabled rule will execute for every login operation (interactive or otherwise), every silent authentication, and every time a user-credentials-related Access Token is generated for an API call. This means that even in small scale deployments, performance can be a concern, which will only be exacerbated as the scale of deployment increases.

Prefer to implement execution based on conditional logic. For example, to run a rule for only specific applications, check on a specific clientID or for specific clientMetadata—especially when checking against a single clientMetadata value, common across multiple applications. Using clientMetadata can also make adding new clients (as well as reading rule code) easier, especially if you have a large number of applications defined, by reducing the code changes or configuration values needed between environments.

Client metadata for an application can be set manually via the Auth0 Dashboard by going to Application Settings > Advanced Settings > Application Metadata or programmatically via the use of the Auth0 Management API's Update a client endpoint.

For optimal performance, write rules that complete as soon as possible. For example, if a rule has three checks to decide if it should run, use the first check to eliminate the majority of cases, followed by the check to eliminate the next largest set of cases, and so on and so forth. At the end of each check, remember to execute the callback function, ideally combined with a (JavaScript) return in order to exit the (rule) function. To learn more, read Rules Execution Best Practices.

Calls to APIs, especially calls to third-party APIs, can slow down login response time and can cause rule timeout failures due to call latency, ultimately leading to authentication error situations. We recommend keeping API requests to a minimum wherever possible within a rule and avoiding excessive calls to paid services. We also recommend you avoid potential security exposure by limiting what is sent to any API, third-party or otherwise.

The global object can be used to cache information from API calls, which can subsequently be used across all rules that execute in the pipeline. Prefer to use this to store information instead of repeatedly calling an API. Additionally, the global object can also be used to cache other information between executing rules.

If you have rules that call paid services, such as sending SMS messages via Twilio, make sure that you only use those services when necessary. This not only provides performance enhancement, but also helps to avoid extra charges. To help reduce calls to paid services:

• Disallow public sign-ups to reduce the number of users who can sign up and trigger calls to paid services

• Ensure that a rule only gets triggered for an authorized subset of users or other appropriate conditions. For example, you may want to add logic that checks if a user has a particular email domain, role/group, or subscription level before triggering the call to the paid service.

Try to avoid calls to the Auth0 Management API. The Auth0 Management API is rate limited, which will still be a consideration even when using the auth0 object (so be sure to use it sparingly). To learn more, read Management API Endpoint Rate Limits.

In addition, Management API functions take varying degrees of time to perform, so will incur varying degrees of latency; calling the Management API's List or Search users endpoint, for example, should be kept to a minimum and performed only where absolutely necessary—even when executed via the auth0 object.

We have expanded connection-related properties available to the rules context object, so you can obtain connection info from the context object instead of needing to call the Auth0 Management API. To learn more, read Context Object Properties in Rules.

To see this in action, if you are using the Check if user email domain matches configured domain rule template, check out the latest version on Github or navigate to Auth0 Dashboard > Auth Pipeline > Rules, and select Create. Note: the recent changes will not alter functionality but will improve the performance of rules that had once relied on calls to the Management API.

Removing calls to the Management API (as well as the extra call required to get the appropriate Access Token) will make your rule code perform better and be more reliable.

When calling APIs or accessing external services, consider specifying explicit timeout(s). The specific timeout value you choose will typically vary based on your use case, but in general, choosing one that is as low as possible—while bearing in mind the performance characteristics of the external service—is advised.

Whether you choose to use explicit timeouts or implicit timeout processing, always be sure to cater to error and/or exception conditions that may occur as a result of any timeout period expiration. To learn more, read Error Handling Best Practices.

When you exceed your rate limits, you'll need to reduce the number of calls you make to Auth0. The specifics depend on your use case, but here are some recommendations:

• Cache /.well-known/* responses: This information does not change frequently, so you can usually cache it to reduce the number of times you need to call Auth0.

• Consider requesting an id_token instead of calling /userinfo to get information about the user.

• Reduce bulk calls, such as bulk delete or bulk unlock.

• Rules Best Practices
• Error Handling Best Practices
• Debugging Best Practices