Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs-dev.auth0-mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The pre-user-registration trigger runs when a user attempts to register through a Database or connection, before the user is created. Use this trigger to add metadata to the user profile before it is created or to deny a registration with custom logic.
Diagram showing the Actions Pre User Registration Flow.
Actions in this flow are blocking (synchronous): they execute as part of the trigger’s process and prevent the rest of the Auth0 pipeline from running until the Action completes.
You cannot currently use pre-user-registration Actions to add metadata to passwordless users.

​
References

  • Event object: Provides contextual information about the request to register a new user.
  • API object: Provides methods for changing the behavior of the flow.

​
Common use cases

​
Deny registration by location

A pre-user-registration Action can be used to prevent a user from signing up: 
/**
 * @param {Event} event - Details about the context and user that is attempting to register.
 * @param {PreUserRegistrationAPI} api - Interface whose methods can be used to change the behavior of the signup.
 */
exports.onExecutePreUserRegistration = async (event, api) => {
  if (event.request.geoip.continentCode === "NA") {

    // localize the error message 
    const LOCALIZED_MESSAGES = {
      en: 'You are not allowed to register.',
      es: 'No tienes permitido registrarte.'
    };

    const userMessage = LOCALIZED_MESSAGES[event.request.language] || LOCALIZED_MESSAGES['en'];
    api.access.deny('no_signups_from_north_america', userMessage);
  }
};

​
Set metadata in the user profile

A pre-user-registration Action can be used to add metadata to the user profile before it is created: 
/**
 * @param {Event} event - Details about the context and user that is attempting to register.
 * @param {PreUserRegistrationAPI} api - Interface whose methods can be used to change the behavior of the signup.
 */
exports.onExecutePreUserRegistration = async (event, api) => {
  api.user.setUserMetadata("screen_name", "username");
};

​
Store a user ID from another system in the user profile

A pre-user-registration Action can be used to store a user ID from another system in the user profile: 
const axios = require('axios');

const REQUEST_TIMEOUT = 2000; // Example timeout

/**
 * @param {Event} event - Details about the context and user that is attempting to register.
 * @param {PreUserRegistrationAPI} api - Interface whose methods can be used to change the behavior of the signup.
 */
exports.onExecutePreUserRegistration = async (event, api) => {
  try {
    // Set a secret USER_SERVICE_URL = 'https://yourservice.com'
    const remoteUser = await axios.get(event.secrets.USER_SERVICE_URL, {
      timeout: REQUEST_TIMEOUT,
      params: {
        email: event.user.email 
      }
    });

    if (remoteUser) {
      api.user.setAppMetadata('my-api-user-id', remoteUser.id); 
    }
  } catch (err) {
    api.validation.error('custom_error', 'Custom Error');
  }
};
To use an npm library like axios, you must add the library to the Action as a dependency. To learn more, read the “Add a dependency” section in Write Your First Action.

​
Deny access to specific JA3/JA4 fingerprints

The event.security_context object contains the JA3/JA4 fingerprint values for the current transaction: 
/**
 * @param {Event} event - Details about the context and user that is attempting to register.
 * @param {PreUserRegistrationAPI} api - Interface whose methods can be used to change the behavior of the signup.
 */
exports.onExecutePreUserRegistration = async (event, api) => {
  const clientJa4 = event?.security_context?.ja4;
  console.log('[ACTION]', {clientJa4});
  const badFingerprints = ['t13d1517h2_8daaf6152771_b6f405a00624','t13d1516h2_8daaf6152771_d8a2da3f94cd'];
  if (clientJa4 && badFingerprints.includes(clientJa4)){
    api.access.deny('suspicious_tls_fingerprint', 'Your TLS fingerprint has been flagged as suspicious');
  }
};