Action Coding Guidelines

Actions code should be performant, secure, and clear, so debugging takes less time and effort. Follow our guidelines below to write Action code like a pro!

Actions basics

  • Use the minimum number of HTTP requests possible and set a reasonable timeout (less than 10 seconds) to avoid accumulated requests during login.

  • Use application metadata to filter for specific applications to determine if an Action should be run.

  • Ensure that Actions, which provide verification or trigger MFA, cannot be bypassed unintentionally or maliciously.

  • Actions should never intentionally throw an error; if processes stop because of an error or condition, use the appropriate api method like api.access.deny().

  • Use event.request.hostname for the domain used in Authentication API calls; this could be the default Auth0 tenant domain or a custom domain.

Coding basics

  • Check for strict equals === with any incoming or stored data.

  • Use a return statement when the Action process should stop.

  • Run a code linter, like ESLint, and an analyzer, like Semgrep, to improve code quality and find issues automatically.

Security basics

  • Do not transmit unencrypted personally-identifiable information (PII) in plain sight, like in URLs or error messages.

  • Always use HTTPS URLs for redirects and API calls.

  • AllowList IP addresses when possible.

  • Watch for incoming data that can be tampered with (URL parameters, user agent, and so on).

Defensive coding

  • Catch errors and handle as necessary.

  • Use guard clauses and return early if the Action processing should not continue.

Logging

  • Never log sensitive data, secrets, or PII.

  • Stay under the maximum of 256 characters logged per Action.

Dependencies

  • Use trusted and maintained packages.

  • Check for outstanding CVEs using npm's audit feature or an automated dependency checker connected to a repository.

  • Use the latest version of a package when possible.

User data

  • Check if an email is verified with event.user.email_verified if it is being used in a sensitive or high-security context.

  • Different Connections provide different user profile data; the only guaranteed user profile field is the user_id.

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.