Action Coding Guidelines

Write clear, concise, and secure Actions code with our coding guidelines.

Follow the guidelines below to write performant, secure, and clear Actions code for a streamlined production environment.

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.

  • Example: application specific values or application grouping values used to variate partially or fully the Action execution.

• Use user_metadata/app_metadata to persist custom data in the user profile.

  • Example: user preferences or state values.

• Use transaction metadata to share data between post-login triggers during the same execution.

  • Example: values retrieved from external services or calculated that need to be reused across subsequent Actions and are related to the current execution.

• Use cache for data to be shared by Actions belonging to different executions.

  • Example: values retrieved from external services or calculated that need to be reused by Actions and are unrelated to the user or the specific current execution.

• 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 write secrets or sensitive code artifacts in plain text as part of your Actions code. Instead, use the Secrets Manager or leverage your own manager by integrating it within the Actions code.
• 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.