One of our customers uses in their organization well-known SSO provider. Sitecore instance that they were using was still missing this integration. Integration itself is not a challenge as it is well described in the Sitecore documentation (https://doc.sitecore.com/xp/en/developers/latest/platform-administration-and-architecture/authentication-and-authorization.html). 

The challenge that we faced was related to the migration of the users roles from existing accounts to the new accounts created after SSO authentication.  

Manual migration would take too much time, so we used a different approach.  

Sitecore event – OnUserCreated 

Sitecore provides many customization options thanks to multiple pipelines and events that are available for every development team.  

Our goal was to migrate roles for every user that authenticates first time within SSO instead of the local Sitecore account. When a user authenticates the first time, a new account is created and this is a great place to add some customization, thanks to the OnUserCreated event being triggered by Sitecore.  

First we start with event registration: 
 
<sitecore role:require="Standalone or ContentManagement"> 
<events> 
<event name="user:created"> 
<handler type="Konabos.Foundation.Security.Events.SSOUserCreationEvent, Konabos.Foundation.Security" method="OnUserCreated" resolve="true" /> 
</event> 
</events> 
</sitecore> 

It is worth noting at this point that we want to use our handler only on standalone Sitecore instances or ContentManagement instances. There is no need to add it to ContentDelivery or other roles.  

Migration flow 

To migrate accounts roles we decided on the following flow: 

• for authenticated users, get an email from the SSO 
• try to find a user with the same email address in the existing database (Sitecore domain) 
• if the user has been found, migrate the roles 
• when the process is successful, lock the local account 

Empty class can look as follows: 
 
namespace Konabos.Foundation.Security.Events 
{ 
    public class SsoUserCreationEvent 
    { 
        public void OnUserCreated(Object o, EventArgs args) 
        { 
            var scEventArgs = (SitecoreEventArgs)args; 
            var user = (MembershipUser)scEventArgs.Parameters[0]; 
            // implement algorithm 
        } 
    } 
} 

OnUserCreated method receives in the arguments an information about the user that we extract in the first two lines of the method. Extracted information contains data of a user that was authenticated within SSO provider. 

Then to implement the algorithm we can use the following code: 
 
// validate if user should be processed 
if(ShouldWeProcessThisUser(user.UserName)) 
{ 
    // get user’s email 
    var userEmail = user.UserName.Split('\\')[1]; 
    var existingUsersCollection = Membership.FindUsersByEmail(userEmail); 
    // find existing users 
    if (existingUsersCollection.Count > 0) 
    { 
        var sitecoreUser = Sitecore.Security.Accounts.User.FromName(user.UserName, true); 
        var sitecoreUserProfile = sitecoreUser.Profile; 
        // for every user, get the profile and assign found roles to the new user 
        foreach (MembershipUser existingUser in existingUsersCollection) 
        { 
            var roles = Roles.GetRolesForUser(existingUser.UserName); 
            foreach(var role in roles) 
            { 
                Roles.AddUserToRole(user.UserName, role); 
             } 
            // lock existing user 
            existingUser.IsApproved = false; 
            var existingSitecoreUser = Sitecore.Security.Accounts.User.FromName(existingUser.UserName, true); 
            var existingSitecoreUserProfile = existingSitecoreUser.Profile; 
            // if existing user is administrator, make new user administrator too 
            if (existingSitecoreUserProfile.IsAdministrator) 
            { 
                sitecoreUserProfile.IsAdministrator = true;
                sitecoreUserProfile.Save(); 
            } 
            Membership.UpdateUser(existingUser); 
        } 
    } 
    else 
    { 
        // if no roles were found, assign basic role so use can access Sitecore panel 
        Roles.AddUserToRole(user.UserName, "sitecore\\Sitecore Client Users"); 
    } 
} 

The above code is everything that you need to start with if you are looking for a smart way of roles migration. As you probably noticed we are not sharing the implementation of the ShouldWeProcessThisUser method as it can be very specific to every project. You can validate users based on the domain, email, and/or any other data that you decided to share via SSO.  

If you work on a smaller implementation you may not even need any validation and simply apply all the steps to all users that authenticate with SSO of your choice. 

Hopefully, a shared approach will help you to develop a solution that answers your needs.