Rules

Rules are JavaScript functions that execute when a user authenticates to your application. They run once the authentication process is complete, and you can use them to customize and extend Auth0's capabilities.

Rule Flow

  1. An app initiates an authentication request to Auth0.
  2. Auth0 routes the request to an Identity Provider through a configured connection.
  3. The user authenticates successfully.
  4. The ID Token and/or Access Token) is passed through the Rules pipeline, then sent to the app.

What can I use Rules for?

Among many possibilities, rules can be used to:

  • Enrich user profiles: query for information on the user from a database/API, and add it to the user profile object.
  • Create authorization rules based on complex logic (anything that can be written in JavaScript).
  • Normalize attributes from different providers beyond what is provided by Auth0.
  • Reuse information from existing databases or APIs for migration scenarios.
  • Keep a white-list of users and deny access based on email.
  • Notify other systems through an API when a login happens in real-time.
  • Enable counters or persist other information. For information on storing user data, see: Metadata in Rules.
  • Modify tokens: Change the returned scopes of the Access Token and/or add claims to it, and to the ID Token.

For rules that call Auth0 APIs, you should always handle rate limiting by checking the X-RateLimit-Remaining header and acting appropriately when the number returned nears 0. You should also add logic to handle cases in which you exceed the provided rate limits and receive the HTTP Status Code 429 (Too Many Requests); in this case, if a re-try is needed, it is best to allow for a back-off to avoid going into an infinite re-try loop. For more information about rate limits, see Rate Limit Policy For Auth0 APIs.

Syntax

A Rule is a function with the following arguments:

  • user: the user object as it comes from the identity provider. Check out the User Object in Rules page for a list of the available user properties.

  • context: an object containing contextual information of the current authentication transaction, such as the user's IP address, application, or location. Check out the Context Object in Rules page for a list of the available context properties.

  • callback: a function to send potentially modified tokens back to Auth0, or an error. Because of the async nature of Node.js, it is important to always call the callback function or else the script will timeout.

Execution order

Rules execute in the order shown on the Auth0 Dashboard. If a rule depends on the execution of another rule, move the dependent rule lower in the list.

Available modules

For security reasons, your Rules code executes isolated from the code of other Auth0 tenants in a sandbox.

Within the sandbox, you can access the full power of Node.js with a large number of Node.js modules. For a list of currently supported sandbox modules, see Node.js Modules Available in Rules