HeadlessUserDiscoveryHandler Interface

Use this interface to create a headless user discovery handler that you implement during the headless passwordless login flow.

Namespace

Auth

Usage

With headless passwordless login, you can build a flow where a user logs in to a headless, off-platform app by entering their email address, phone number, or another identifier that you choose. After you collect the user's identifier, your app passes it to the headless passwordless login endpoint in a login_hint parameter. At this point, you can use a headless user discovery handler to find the user account associated with the data that you passed in the login_hint. With a handler, you can give users more ways to log in and have more control over your headless passwordless login implementation.

For more information, see these resources.

HeadlessUserDiscoveryHandler Methods

The following are methods for HeadlessUserDiscoveryHandler.

discoverUserFromLoginHint(networkId, loginHint, verificationAction, customDataJson, requestAttributes)

Finds a user's Salesforce account based on user information, such as their email address, phone number, or other data, that's passed to the /services/auth/headless/init/passwordless/login endpoint during headless passwordless login.

Signature

public Auth.HeadlessUserDiscoveryResponse discoverUserFromLoginHint(Id networkId, String loginHint, Auth.VerificationAction verificationAction, String customDataJson, Map<String,String> requestAttributes)

Parameters

networkId: Type: Id; The ID of the Experience Cloud site where your headless app sends requests.
loginHint: Type: String; Information about the user that Salesforce can use to find their associated account, such as their email address or phone number.
verificationAction: Type: Auth.VerificationAction; The verification method that's used to log the user in, either email or SMS.
customDataJson: Type: String; Custom user data, such as first name, that you collect when the user logs in to your headless app.
requestAtttibutes: Type: Map<String,String>; Information about the login request that's based on the user’s browser state when accessing the login page. requestAttributes passes in the CommunityUrl, IpAddress, UserAgent, Platform, Application, City, Country, and Subdivision values. The City, Country, and Subdivision values come from IP geolocation.

Return Value

Type: Auth.HeadlessUserDiscoveryResponse

If the handler finds a user, it returns a user ID. If not, it returns an error message.

HeadlessUserDiscoveryHandler Example Implementation

Here's an example implementation of the Auth.HeadlessUserDiscoveryHandler interface. This example supports login with email and login with SMS.

The discoverUserFromLoginHint method uses custom logic to search for a user account with a verified email address or phone number that matches the data passed in the login hint. As a security best practice, Salesforce always recommends writing code to determine if the user's email address or phone number is verified.

For users logging in with email, the custom logic first checks whether the email address passed in the login hint is in a valid format. Then, to look for a verified Salesforce email address that matches the email address passed in the login hint, it queries the TwoFactorMethodsInfo object. If successful, it returns an instance of Auth.HeadlessUserDiscoveryResponse with the user ID. If something goes wrong, it returns an instance of Auth.HeadlessUserDiscoveryResponse with a custom error message. In this example, it returns error messages when the email address format isn't valid, the email address isn't verified, there's no user with that email address, or there are multiple users with that email address.

For users logging in with SMS, the custom logic is similar. It checks whether the phone number passed in the login hint is in a valid format. Then, it looks for a verified Salesforce phone number that matches the phone number passed in the login hint. If successful, it returns an instance of Auth.HeadlessUserDiscoveryResponse with the user ID, and if not, it returns custom error messages.

Apex Reference Guide