How to Set Custom User IDs with Actions for New Users in Database Connections - Auth0 Docs

Custom User ID Assignment with Actions

The custom user ID assignment with Actions feature is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta's Master Subscription Agreement.

By default, when creating a new user, Auth0 automatically generates a user_id attribute as a unique identifier for that user. Database connections support setting a custom user ID during user creation. You may want to specify your own user IDs if you need standardized formatting or consistency across systems. For example:

• Maintaining an existing user ID structure when migrating from another identity provider to Auth0 so that tokens, audit logs, and integrations remain consistent.
• Ensuring compatibility with data or billing systems that require specific formats like UUID v4 or sequential integer user IDs.
• Matching user IDs to primary keys in an internal database or CRM for simplified data joins and reporting.
• Composing deterministic user IDs from known attributes, like tenant names or app metadata.

You can set a custom user_id by calling api.user.setUserId() in an Action added to the pre-user-registration trigger, which fires before a new user profile is created.

How User IDs Are Determined

In the user profile, the identities array contains objects with information from each identity provider with which the user authenticates. Setting a custom user ID sets the user_id attribute in the identities array object for the database connection. There are different ways to set a custom identities user ID depending on how you create the user. The following table summarizes available creation methods and how the user_id is set by precedence:

In summary, a user ID set with api.user.setUserId() in a pre-user-registration Action takes precedence over other methods of setting a custom user ID, but the pre-user-registration trigger does not fire for bulk import jobs. Additionally, Auth0 sets the user profile’s root-level user_id based on the profile’s primary identity, which is the first identity in the identities array. The root-level user_id is the primary identity’s user ID prefixed with the connection strategy (for example, auth0|your_custom_id). The root-level user_id is used as the value for the sub claim, so make sure downstream systems expect the prefixed value.

Set Custom User IDs with a pre-user-registration Action

To set a custom user_id with a pre-user-registration Action, you need to create the Action, write the code that sets the user ID to the value you want, and then add the Action to the pre-user-registration trigger.

Create the Action

Go to Dashboard > Actions > Library. Select Create Action, then choose Create Custom Action from the drop-down menu. In the Create Action window that opens, enter the following fields:

• Name: Choose a name for your action, like “Set Custom User ID”.
• Trigger: Select Pre User Registration.
• Runtime: Choose your Node runtime.

Then select Create to go to the Actions code editor for the new Action.

Write the Action Code

In the Actions code editor, write your Action code using api.user.setUserId() to set the user ID based on your use case. Custom user IDs must meet the following requirements:

• The user_id must be unique within the connection. If a user with the specified user_id already exists, creation fails.
• The user_id must pass the same validation as the Management API Create a user endpoint’s user_id body parameter.

If user creation fails due to user ID issues, check your tenant logs for log type fs (failed sign-up).

Example: Generate a UUID v4

exports.onExecutePreUserRegistration = async (event, api) => {
  const crypto = require('crypto');
  api.user.setUserId(crypto.randomUUID());
};

Example: Generate a specific UUID version

If you need a specific UUID version (v1, v5, v7, etc.), add the uuid npm package as a dependency and use it in your Action:

const { v7: uuidv7 } = require('uuid');

exports.onExecutePreUserRegistration = async (event, api) => {
  api.user.setUserId(uuidv7());
};

Example: Compose an ID from sign-up data

You can compose a deterministic user ID from sign-up data, like an app_metadata value:

exports.onExecutePreUserRegistration = async (event, api) => {
  const externalId = event.user.app_metadata?.external_id;
  if (externalId) {
    api.user.setUserId(externalId);
  }
};

Once you finish writing and testing the Action, select Deploy.

Add the Action to the Trigger

After you deploy the Action, go to Dashboard > Actions > Triggers > Pre User Registration. In the Add Action section on the right, under Custom, drag the new Action you created into the flow between Start and Complete. Then select Apply.

Limitations

• Setting a custom user ID with the pre-user-registration trigger is not supported for passwordless connections.
• The pre-user-registration trigger does not fire for bulk import jobs.
• You cannot set a custom user_id for users logging in via social or enterprise connections because those IDs are provided by the external identity provider.
• You cannot change an existing user’s user_id.