Linking Providers, Account and Profile Management

Users may be prompted to add a new login provider to their existing account when they log in. Login providers can also be added to or removed from existing accounts when the Authentication worker is in account management mode.

For this functionality to work seamlessly, your subsite should be set to enforce HTTPS connections.

General Principles

Provider linking is all about the login methods associated with user accounts, it does not link existing accounts together. Login providers can only be added to an account if they are not already linked to another account. If a login provider is already linked to an account, the user will be logged into your site as that account user. Login providers do not exist anywhere in the platform other than as login methods linked to existing accounts.

Note that some providers are configured to never allow linking. The LDAP and ADFS providers are most likely to be used on internal intranets that mirror user groups. Allowing different login providers to link to these accounts would not be appropriate. There are "basic" versions of these providers which do allow linking but have all group mirroring disabled. See the articles for each provider type for any special considerations around linking.

To enable linking, as well as the settings in each provider (see below) the global linkOnLogin property needs to be true.

Provider Linking on Login

When a user logs into your site using an external provider, the Authentication worker checks the email address returned from that provider against those of existing accounts. If a match is found, and if the account being used to log in with is not already in use, the user will have up to three options.

Login with Existing Account

If the Authentication worker finds an existing account that may belong to the user, they could choose to log in using a provider already set up for that account. The user will have to enter the username and password for an existing provider (or authenticate with the third party provider) and they'll be logged in as that account - the provider they originally chose is abandoned.

Example

1. A user already has an account on your site with Facebook as a login provider
2. They return to your site at a later date and choose to log in with Google
3. They authenticate with Google
4. The user is informed that an account with a matching email address exists and is presented with the option to log in with Facebook
5. The user chooses to authenticate with Facebook and is logged into your site with their existing account
6. No record is kept of their Google authentication

Add Login Provider to Existing Account

If allowLinkingFromThisProvider and allowLinkingToThisProvider are both true in the provider the user is logging in with, accounts that have a matching email address and also have allowLinkingToThisProvider set as true in the providers associated with those accounts, will be presented to the user, with the option of adding the new/current provider to an existing account.

Example

1. A user already has an account on your site with Facebook as a login provider
2. They return to your site at a later date and choose to log in with Google
3. They authenticate with Google
4. The user is informed that an account with a matching email address exists and is presented with the option to add Google as a new provider to that account
5. The user chooses to add Google as a login provider to the existing account. They may have to enter a PIN which gets emailed to them or could simply receive a notification email - see below
6. The user is logged into your site
7. The user's existing account now has two login providers, Facebook and Google, and either could be used to log in with in the future

Create a New Account

Rather than adding a new provider to an existing account, the user could choose to create a brand new account. If they do this they'll end up with two accounts, each with a different login provider. From this point onwards they'll be treated as entirely separate users and will not be able to link these accounts together. It would be possible to remove a provider from one account (replacing it with another) and start this process again.

Example

1. A user already has an account on your site with Facebook as a login provider
2. They return to your site at a later date and choose to log in with Google
3. They authenticate with Google
4. The user is informed that an account with a matching email address exists and is presented with the option to create a new account
5. The user chooses to create a new account and is logged into your site
6. The user now has two accounts, one with Facebook as a provider, one with Google as a provider
7. Future logins with Facebook or Google do not prompt the user to add either provider to either account (because both providers are now linked to separate accounts)

Provider Linking in Account Management Mode

Once a user has logged in they may have the option to add additional login providers to their existing account, using framework templates like My Account. This functionality can be disabled globally in the worker configuration.

In account management mode providers that have allowLinkingFromThisProvider and allowLinkingToThisProvider set as true are shown in a list to the user if their existing provider also has allowLinkingToThisProvider set as true. If allowLinkingToThisProvider is set as false, any users entering account management mode will just see a list of their account's current authentication methods.

For account management to work, all of the login providers associated with an existing account must allow account linking. In normal use you shouldn't find accounts that have a mix of providers that do and don't allow linking, but this could happen if you make changes to your provider configuration.

To add a provider to an account the user selects the new provider from the list and authenticates with that provider. If a provider is already linked to another account the user will receive a message informing them that the provider is already in use.

There is no requirement for login provider accounts added in this way to have the same email address. It is also possible to add two login providers of the same type to an account, as long as they have different email addresses.

When a user adds a new provider to their account successfully, the new provider becomes the provider of their current session on the site.

Emails

The Authentication worker configuration's userLinkingEmailMode property has three options for the emails generated during account linking: none, notification and confirmationrequired. These options are set once and applied to all configured providers.

The "from" email address used by these emails is set when the call to renderLoginForm is made. This is supplied by the site frameworks and generally set in a subsite's configuration.

Note that emails are only sent during linking at the login stage. Emails aren't sent in account management mode.

Confirmation Required

This is the default mode. In this mode a PIN is emailed to the existing account's registered email address and the user is presented with an input box. The user must enter the PIN before the new provider is added to the account.  If the PIN is entered incorrectly three times the user will have to start the linking process again.

None

No emails are sent. When a user links on login new providers are added to their account without any further confirmation.

Notification

When a user links on login a notification email is sent to the email address of the account being linked to. The provider is added without any further confirmation.

Updating Profiles

When a user first creates an account, whether by registering directly with your site or authenticating with an external provider, personal information about them will be saved in their user profile. For direct registrations (iCM Site User providers) the information gathered will depend upon your site registration process and form. The information returned from external providers is listed in each of the Provider Types articles. 

By default, user profiles are not updated when a returning user logs in (ie they have registered with your site by logging in with Google, at a later date they update their details with Google, then log back into your site). If you want profile details to be updated each time a user logs in with an external provider, set the fields to be updated in the profileFieldsToUpdate parameter. This is an array of the abstract classes described in Site User Profile Mapping (ie the target mappings defined in the userProfileAttributeMapping), not the profile field names themselves. Those listed will be updated each time a user logs in with that provider. Refer to the ADFS Provider documentation to see an example of the profileFieldsToUpdate parameter being used.

User profiles are not updated should a user add a new login provider to their account. The authentication process also does not update any personal details in a third party system. If this is required, this could be achieved via changes to the form used by the users to update their details.

Updating Email Addresses

Account user profiles include a user's email address. When a user logs in with an external provider that is already linked to their account, if the Authentication worker detects that the email address returned from the provider is different to the email address of the account, the user is notified and has three options.

Updating an email address will automatically update the email address held in the user's account user profile.

Ignoring the email address adds the address from the provider to an ignore list, stored as a hashed value in the iCM database against that user. Future occurrences of mismatched emails will be ignored.

Cancelling the prompt ignores the email address mismatch this time. Future logins will generate the prompt again.