The setUserByConnection Function Does Not Validate Users Against Upstream Identity Providers

This article clarifies the validation behavior of the api.authentication.setUserByConnection function. Specifically, it addresses whether this function performs real-time validation against an upstream Identity Provider (IdP) when used within an Auth0 Custom Token Exchange Action.

• Custom Token Exchange
• Actions
• api.authentication.setUserByConnection
• Enterprise Connections
• Social Connections

The api.authentication.setUserByConnection function does not contact an upstream IdP to validate a user's existence. The function operates on the principle that the incoming token has already been validated. The key behaviors are:

• Simulated IdP Response: The function simulates a successful authentication from a federated IdP. It trusts the user_profile object passed to it as the payload that an IdP would typically return after a successful user authentication.

• Internal User Store Interaction: For social and enterprise connections, the function's scope is limited to Auth0's internal user store. It saves or updates the user's profile within Auth0 but does not create, modify, or validate the user in the upstream IdP's directory.

• Developer-Owned Validation: The Custom Token Exchange framework requires the developer to validate the incoming subject_token. The Action script must securely verify the token's authenticity and integrity before calling setUserByConnection to assert the user's identity.

The correct implementation is to first validate the external token and then use the function to create or update the user profile in Auth0:

1. Within the onExecuteTokenExchange Action, implement custom logic to securely decode and validate the event.transaction.subject_token. This step is critical to prevent security risks such as token spoofing.

2. After successfully validating the token, extract the necessary user attributes to build a user_profile object. NOTE: The user_profile object must include a user_id that is the unique identifier for the user within the external IdP for that specific connection.

3. Call the api.authentication.setUserByConnection function, passing the connection name and the prepared user_profile object.

Auth0 then uses the provided profile to either create a new user or update an existing one in its user store.