Please note that rules also run during the token refresh flow.
Authentication transaction flow
An app initiates an authentication request to Auth0.
Auth0 routes the request to an Identity Provider through a configured connection.
The user authenticates successfully.
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.
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.
There are many uses for Rules. In the Dashboard, you can find example templates to help you get started with Rules under Rules > Create Rule. The examples help you with things like MFA, external webhooks, enriching profile information, altering the authentication process, and more. You can use these templates as a starting point, then customizing them to suit your specific needs.
How to Handle Rate Limits when calling Auth0 APIs
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.
A Rule is a function with the following arguments:
user: the user object as it comes from the identity provider. See User Object in Rules for a list of the available user properties. (However, if you execute the rule in the context of a call made to the Delegation endpoint, the
userobject will also include the original JSON Web Token (JWT) claims.)
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
callbackfunction or else the script will timeout.
In general, 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.
Rules run at a specific point within the authentication transaction flow. After rules run, the Redirect, Multi-factor Authentication (MFA), and Consent features must still run (in that order and only if they are required).