Skip to main content

Auth0 Actions

Overview​

Actions are secure, tenant-specific, versioned functions written in Node.js that execute at certain points within the Auth0 platform. Actions are used to customize and extend Auth0's capabilities with custom logic. Actions are not to be confused with Auth0 Rules. Rules allow you to handle the authentication flow unlike actions which let you handle multiple flows such as authentication, pre and post user registration and so on. It is generally advised to migrate from rules to actions; more information about this can be found in the resources section.=

How do Auth0 Actions work?​

The processes that can be extended in this way are called flows. Each flow is made up of one or more triggers and represents the logical pipeline through which information moves during a single point in the Auth0 journey. Multiple Actions can be added to a trigger, with each Action executing in the order in which it was placed. Some triggers are executed synchronously, blocking the flow in which they are involved, and some are executed asynchronously, as indicated in the table below.

FlowRunsTriggersExecutionUse Cases
LoginAs a user logs inpost-loginSynchronous- Our very own progressive profiling - Call internal APIs or other third parties such as Exponea to enrich user profiles - Send notifications - Redirection to different flows
Pre User RegistrationBefore a user is added to a Database or Passwordless Connection.pre-user-registrationSynchronous- Block malicious customers or accounts - Enrich app or user metadata
Post User RegistrationAfter a user is added to a Database or Passwordless Connection.post-user-registrationAsynchronous- Create a new user record in Exponea
Post Change PasswordAfter a password is changed for a Database Connection user.post-change-passwordAsynchronous- Revoke a users session in other systems or clients

Benefits of Actions​

  • As described in the tooling documentation, actions can be debugged using the Real-time Webtask Logs extension
  • Actions unlike Rules are versioned, so you are able to roll back to previous versions.
  • Because Actions are versioned you can edit and test without affecting production.
  • Actions have access to more rich type information and inline documentation which makes it easier to discover capabilities. More information can be found by visiting the Event and API Object documentation for each flow. Links can be found in the resources section.
  • Access to npm packages
  • Observability via Auth0 log streaming service. More information can be found here
  • Multiple actions per trigger

Action Coding Guidelines​

Actions code should be performant, secure, and clear, so debugging takes less time and effort. Follow Auth0s guidelines on how to write Action code. Below i've included guidelines for redirect actions in the login flow as this is our primary use case.

Redirect Actions in the Login Flow​

  • The token returned by api.redirect.encodeToken is signed but not encrypted, so sensitive data or PII should not be included in the payload.
  • The Login Flow runs after a successful login, which includes:
    • SSO (no login form shown)
    • Silent authentication (checking a session using prompt=none in the authorization URL)
    • Refresh token exchange (no user interaction)
    • RO password grants (credentials gathered from an application and exchanged with the token endpoint)
  • Actions that redirect need to take the above cases into account and either deny access if interaction is required or intensionally allow bypassing, which puts the burden on the application requesting login.

Actions Limitations​

Actions are goverened by a strict list of limitations. They are mostly in place so that actions do not introduce latency as this can stop a user from completing a flow.

A complete list of limtations can be found here.

The most notable are:

  • Each Action should not exceed 100 kB. The larger the size, the more latency is introduced, which may have an impact on the performance of your system. This size limit limit does not include any npm modules that may be referenced as part of any require statements.
  • Each execution of a flow must complete in 20 seconds or less or the processing will end in an error. Limiting HTTP requests is the best way to keep within this time limit. Actions that are not limited by this time limit while on the external page.
  • Each execution of a flow must complete in 20 seconds or less or the processing will end in an error. Limiting long-running processes, like outbound HTTP requests without a timeout, is necessary to keep within this time limit. An Action that redirects users to an external page has a separate timeout before the redirect and after.
  • Calls made to the Auth0 Management API and User Metadata updates are rate limited.
  • Each Action may have a maximum of 10 npm modules. We should try keep Actions vanilla as possible and avoid using npm modules

Testing​

There are serveral ways to debug Auth0 Actions. Most notably in the tooling section we have already covered Real-time Webtask Logs. In addition to that you are able to verify end-to-end flows via the tenant logs as wlel as simulating events in the Action GUI.

Testing invidual actions​

You can test individual Actions using the Actions Code Editor. The editor's test capability simulates a call to the Action using a sample payload based on the flow with which the Action is associated. To test an individual Action:

  1. Navigate to the Action and locate the action code editor.
  2. Select the play icon / test from the sidebar. Here you are able to edit the payload and analyse the outcome
  3. Select Run

Verify end-to-end flows​

For apost-login Action, you can verify the end-to-end-login flow by executing a login attempt for our tenant:

  1. Navigate to Authentication > Authentication Profile and select Try. A window containing a sample login will open.
  2. Proceed through the login flow. The flow will execute any Actions configured against the post-login flow.

Once complete, you will be redirected to a page that either lists the user profile attributes that your applications will receive or shows an error message explaining what went wrong.

Resources​