There are some sites out there providing guidance to set up SSO with Sitecore, but the steps are a little outdated now with references to areas an Azure that have been migrated to new features. I also didn’t find a way to resolve a common error administrator might encounter with claims.

Planning the Use of Azure AD With Sitecore

Sitecore Roles are going to be assign to the User when they log in based on what Groups they’re part of in Microsoft Entra ID. Since Groups and Roles are aligned you should have this and the Users sorted. It works like this:

1. User goes to Sitecore to log in.
2. User is redirected to Identity Server and sees/uses the SSO button.
3. The User logs in using Azure, which sends what Groups they are a part of back to Identity Server.
4. Identity Server logs the User in and assigns them Sitecore Roles based on which Groups they are a part of.
5. Sitecore stores the User information, which was sent from Entra, including the full name and email address.

This means we will set up Microsoft Entra ID, then Identity Server and finally Sitecore for this ability.

Kamruz Comes Correct

Before we start, I want to note that some of the config file below will be referencing a great trick from my friend Kamruz who posted the fix for random usernames (from step 5 above). You can see the full write up at his post, Prettier Usernames in Sitecore When Using Azure AD or Other Identity Providers.

Configuring Microsoft Configure Entra ID

Register the Application

Go to the Azure portal  and log in.

Then go to Microsoft Entra ID -> Manage -> App registrations.

Click New registration at the top and enter a name, supported account type (single tenant only), and redirect URI (platform = Web and URL for default local is https://localidentityserver.dev.local/signin-oidc) and click on register button.

Now go to the Manage -> Manifest tab and update groupMembershipClaims value to SecurityGroup. and hit Save.

Go to Manage -> Authentication -> Settings tab and check the ID tokens and hit Save (this time at the bottom).

Go to the overview tab and save the Application (client) Id and Directory (tenant) Id which are going to be used in the Sitecore config files later.

Creating Groups for Role Mapping

Sitecore Roles can managed internally, grouping necessary out of the box Roles and custom ones when needed. A group in Entra will be needed for each unique Role that is to be assigned to Users. These groups are needed before proceeding with the Sitecore configuration.

Back in Azure, close the app registration then go to Manage -> Groups inside Microsoft Entra ID, and create a new Group for each Role in Sitecore you need (Administrator, Author, etc.) by clicking New group at the top.

Once added, go to All groups and note the Object Id which you'll need for later.

This can wait for later, but ensure you've added Users to the new Group before testing.

Sitecore Identity Server Configuration

All changes needed for Identity Server are made in the Sitecore.Plugin.IdentityProvider.AzureAd.xml file (the one in the sitecore subfolders and not the root).

Open it and update ClientId and TenantId from the App Registration which was saved in the previous section.
Change Enabled to true.

<?xml version="1.0" encoding="utf-8"?>
<Settings>
  <Sitecore>
    <ExternalIdentityProviders>
      <IdentityProviders>
        <AzureAd type="Sitecore.Plugin.IdentityProviders.IdentityProvider, Sitecore.Plugin.IdentityProviders">
          <AuthenticationScheme>IdS4-AzureAd</AuthenticationScheme>
          <DisplayName>Azure AD</DisplayName>
          <Enabled>true</Enabled>
          <ClientId>[your-value-here]</ClientId>
          <TenantId>[your-OTHER-value-here]</TenantId>
          <MetadataAddress></MetadataAddress>

If you're using an Administrator mapping, uncomment the AzureADUserToAdminUser node and replace the value of Claim1 to the ID from your Groups earlier.

<AzureADUserToAdminUser type="Sitecore.Plugin.IdentityProviders.DefaultClaimsTransformation, Sitecore.Plugin.IdentityProviders">
  <SourceClaims>
    <Claim1 type="groups" value="[unique-group-id]" />
  </SourceClaims>
  <NewClaims>
    <claim1 type="http://www.sitecore.net/identity/claims/isAdmin" value="true"></claim1>
  </NewClaims>
</AzureADUserToAdminUser>

Copy the AzureGroupTransformation node for each Role you want to map and add the Group ID related to if from earlier.

<AzureGroupTransformation type="Sitecore.Plugin.IdentityProviders.DefaultClaimsTransformation, Sitecore.Plugin.IdentityProviders">
  <SourceClaims>
    <Claim1 type="groups" value="[unique-group-id]" />
  </SourceClaims>
  <NewClaims>
    <Claim1 type="role" value="sitecore\Author" />
    <Claim2 type="role" value="sitecore\Analytics Testing" />
  </NewClaims>
</AzureGroupTransformation>

Restart Identity Server and you will now see the Azure AD button.

Sitecore Configuration and Username Trick

The following patch file is a good example of the final phase for this effort. Since I work for MNP you can see I used that domain name. I'll break it down....

Here we restrict the patch to the local or CM instance, and define the domain "mnp".

<sitecore role:require="Standalone or ContentManagement">
    <domainManager set:defaultProvider="config">
        <domains>
            <domain id="mnp" type="Sitecore.Security.Domains.Domain, Sitecore.Kernel">
                <param desc="name">$(id)</param>
                <ensureAnonymousUser>false</ensureAnonymousUser>
            </domain>
        </domains>
    </domainManager>

The domain is referenced under identity providers, where you can also change the button text under caption if you want to not use Identity Server in the future.

    <federatedAuthentication>
        <identityProviders>
            <identityProvider id="SitecoreIdentityServer">
                <domain>mnp</domain>
            </identityProvider>
            <identityProvider id="SitecoreIdentityServer/IdS4-AzureAd" type="Sitecore.Owin.Authentication.Configuration.DefaultIdentityProvider, Sitecore.Owin.Authentication">
                <param desc="name">$(id)</param>
                <param desc="domainManager" type="Sitecore.Abstractions.BaseDomainManager" resolve="true" />
                <caption>MNP Login</caption>
                <icon>/sitecore/shell/themes/standard/Images/24x24/msazure.png</icon>
                <domain>sitecore</domain>
            </identityProvider>
        </identityProviders>

The property initializer area allows us to map the name and email of the User, which will be important in the next step section.

        <propertyInitializer>
            <maps>
                <map name="set IsAdministrator" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication" resolve="true">
                    <data hint="raw:AddData">
                        <target name="IsAdministrator" value="true" />
                    </data>
                </map>
                <map name="set FullName" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication" resolve="true">
                    <data hint="raw:AddData">
                        <source name="name" />
                        <target name="FullName" />
                    </data>
                </map>
                <map name="set Email" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication" resolve="true">
                    <data hint="raw:AddData">
                        <source name="email" />
                        <target name="Email"  />
                    </data>
                </map>
            </maps>
        </propertyInitializer>

Finally, there is an externalUserBuilder adedd which helps with the naming of Users when logging in. You can find it in the Konabos post above, but I wanted to break down the config file here. 

        <identityProvidersPerSites>
            <mapEntry name ="all sites">
                <externalUserBuilder set:type="Sitecore.Feature.Security.Util.CustomUserBuilder, Sitecore.Feature.Security" />
            </mapEntry>
        </identityProvidersPerSites>            
    </federatedAuthentication>
</sitecore>

The Dreaded Header Length Error

Even if you don't get the error, "The size of the request headers is too long" right away, you very well might in the future.

The headers can be too long since all claims are sent back to Sitecore when a User logs in. Direction is provided at Sitecore Support  but does not include steps. The following are the correct steps to resolve this.

1. Go into Microsoft Entra ID -> Enterprise Applications
2. Find the app registration from earlier steps
3. Go to Users and groups -> Add user/group
4. Add only the specific groups that are needed for the Sitecore accounts
5. Go back into App Registrations and open the registered app
6. Go to Token Configuration
7. Find the Groups claim and edit it (add one if it's not there)
8. Change the group type from security groups to Groups assigned to the application
9. Save and try again.

This should correct the headers error when logging in. Good luck with this, and contact me if you get stuck.

---