How Existing User Linking Works with Open ID Connect and Third-Party Account link in Salesforce Single Sign-on

Recently, we have the a Salesforce SSO with Auth0 scenario as below:

• Given: The user has already had a user account in Salesforce

• When: The user logs in Salesforce through Auth0 SSO the first time

• Then: Find the user in salesforce using the email address

  • If found, log the user in Salesforce using the existing Salesforce user account

  • If not found, create a new user account and log the user in.

A question was raised “After the user has logged in Salesforce the first time, if the user changes the email address in Auth0 later on, what would happen? Is the user still able to login through Auth0 SSO the second time?

After some research and experiments, I have realized Third-Party Account Link can elegantly handle this email change scenario. First of all, if you are not familiar with Open ID Connect(OIDC ) flow in salesforce, here is a good read., and as we know , in Salesforce OIDC flow, the createUser or updateUser method in registration handler apex class will be invoked once the user info is retrieved from OpenID Connect Provider (OP), in our case, it is Auth0. Please find the sequence diagrams of the first and following login scenarios

Once the user has successfully logged into Salesforce through Auth0 SSO the first time, a third party link record will be created to link the user record to the remote identity provider info. Run SOQL “SELECT UserId, SsoProviderId, Handle, RemoteIdentifier, Provider FROM ThirdPartyAccountLink where userId = {replace this with your user id}“

Rather than the email address that is used during the first time login, as you can see, in the sample record, the Auth0 user account unique id is stored in RemoteIdentifier field, and this is going to used by the Salesforce platform as the value to identify the user account in Salesforce to log the user in the second time and onwards.

You can also see this link on the user record page as above and revoke the the link if needed.

The following is my registration handler code sample,

• In the createUser method, I check if the user is existing using the email address when creating the user the first time, if the user found, log the user in, otherwise create a new user account.

• In the updateUser method, as it will be only invoked when the user has a third party account link record, I update email change in Salesforce from Auth0 just in case if the third party account link is revoked, so that the email will be used again to identify the existing user.

global with sharing class RegHandlerSample implements Auth.RegistrationHandler {


    global User createUser(Id portalId, Auth.UserData data) {

        User u;

        List<User> users = [SELECT Id FROM User WHERE FederationIdentifier = :data.email];
        if (users.size() == 1) {
            return users.get(0); // if the user is found using email, log the user in
        }
        // Create a new user if no user is found using email
        // ...
        // ...
        return u;
    }

    // if the login user already has a third party link,
    // the update user method will be invoked
    global void updateUser(Id userId, Id portalId, Auth.UserData data) {
        User u = new User(Id = userId);
        u.FirstName = data.firstName;
        u.LastName = data.lastName;
        u.Email = data.email;         // update email change
        //sync email change just in case if the link is revoked, 
        //so that the email will be used again to identify the existing user
        u.FederationIdentifier = data.email;  
        update (u);
    }
}

In conclusion, ThirdPartyAccountLink is used to link a user with an external id in an authentication provider, as long as the user has a ThirdPartyAccountLink record, the updateUser method will be called instead of createUser method, the user can still log into Salesforce through Auth0 SSO the second time even the user has changed the email address in Auth0, because the Auth0 user unique id is going to be used once it is stored in the ThirdPartyAccountLink record, and the email address is only used when the ThirdPartyAccountLink record is not linked to the user.

If you have any questions or suggestions, please feel free to contact me.