docs: add consolidate users system preference

website/docs/docs/authentication/main.md

@@ -10,6 +10,10 @@ SSO users are automatically provisioned when they first authenticate.
 
 **NOTE:**   Changing these settings may require users to do a hard refresh in their browser (CTRL-F5 on Windows and Linux, CMD-R on Mac OSX) before the next time they try to login, or clear their browser cookies and cache.
 
+## Prerequisites
+
+If you are migrating to Single Sign On from username/password based authentication, you should consider enabling merging of identities based on email address, via the ["Consolidate User Logins by Email" system preference](/docs/user-interface/settings/preferences#consolidate-user-logins-by-email), otherwise you will end up with duplicate users.
+
 ## GitHub Authentication
 
 _Eligible plans: all_
@@ -459,7 +463,13 @@ You have attempted to login via your IdP (IdP Initiated Login) which is not supp
 
 Users are identified uniquely by their identity providers. This means that a user that previously logged into PactFlow via username/password with the email "[email protected]" who then authenticates via Github, will be treated as a separate user with separate permissions. 
 
-You can discriminate between users based on the "identity provider" column in our Users UI screen. To reduce the number of users in your account, you can disable any users that no longer login via a particular IDP.
+To enable merging of identities based on email address:
+
+1. Set the "Consolidate User Logins by Email" [system preference](/docs/user-interface/settings/preferences#consolidate-user-logins-by-email)
+2. Delete the duplicated user
+3. Attempt the federated login again. This will link the federated user to the original user, retaining the team assignments, roles, audit trail history etc.
+
+You can discriminate between users based on the "identity provider" column in our Users UI screen. To reduce the number of users in your account, you can disable (or delete) any users that no longer login via a particular IDP.
 
 ### 5. I've enabled SSO, can I disable login via username/password?
 

website/docs/docs/user-interface/settings/preferences.md

@@ -46,4 +46,14 @@ This field specifies the email addresses that will receive notifications about p
 
 For existing accounts, the email addresses of users with the Administrator role have been initialized as the default. For new accounts, the default will be the email address of the account creator. 
 
-Note: Any email address can be added to this field. The owner of the email address does not need to have a PactFlow account.
+Note: Any email address can be added to this field. The owner of the email address does not need to have a PactFlow account.
+
+#### Consolidate User Logins by Email
+
+Allow users to be linked to different identity providers via their email address. When enabled, logins from different identity providers will be considered the same user if they have the same email address.
+
+This setting does not affect existing users that have previously logged in and have a stored identity. To fix this, see the troubleshooting article on [duplicate users](/docs/authentication/main#4-ive-added-an-identity-provider-and-see-duplicate-users).
+
+:::warning
+Do not enable this setting unless you can guarantee the identity providers you use validate the user's email address.
+:::