Use the Sitecore Identity server as a federation gateway

Version: 10.4

Because it is based on Duende IdentityServer, you can use the Sitecore Identity (SI) server as a gateway to one or more external identity providers (or subproviders, sometimes also called inner providers).  IdentityServer Federation Gateway has more information about this concept.

When you configure a subprovider, a login button for this provider appears on the login screen of the SI server.

You must enable the Azure AD identity provider that is included with the SI server. See the {SI_server_root_folder}\sitecore\Sitecore.Plugin.IdentityProvider.AzureAd\Config\readme.txt file for instructions about to do this.

Note

You can configure Azure AD to work with the SI server by authorizing access to web applications using OpenID Connect and Azure Active Directory 

Note

If you see this error: "The reply url specified in the request does not match the reply urls configured for the application:", use the https://[SI Server host name]/signin-oidc URL in the replyUrls section of the application manifest.

Configure subproviders in the Sitecore Identity server

To add a subprovider in the SI server:

  1. Create a new plugin in Visual Studio:

    1. Create a Class Library (.NET 8.0) C# project.

    2. Create a global.json file at the root of the repository:

      RequestResponse
      {
    "msbuild-sdks": {
        "Sitecore.Framework.Runtime.Build": "4.0.0"
    }
}

      Use version 4.0.0 for .NET 8 projects.

    3. Edit the csproj file: add <Sdk Name="Sitecore.Framework.Runtime.Build" /> after the Project node.

    4. Set the target framework to net8.0:

      RequestResponse
      <TargetFramework>net8.0</TargetFramework>

    5. Add other references you need:

      • Microsoft.AspNetCore.Authentication.OpenIdConnect (version 8.0.10) to enable OpenID Connect authentication.

      • Sitecore.Framework.Runtime.Abstractions (version 8.0.1) to enable using runtime abstractions.

      • Reference to Sitecore.Plugin.IdentityProviders project if you need base classes for identity providers.

  2. Configure services for the preferred subprovider according to the instructions for this provider, and specify the SignInScheme  setting as idsrv.external.

    Note

    To use authentication middleware such as AddOpenIdConnect, use the Microsoft.AspNetCore.Authentication.OpenIdConnect package (version 8.0.10 or later). This package is compatible with .NET 8.0.

    Example configuration in ConfigureSitecore.cs in C#:

    RequestResponse
    using Microsoft.AspNetCore.Authentication;   
using Microsoft.Extensions.Configuration;   
using Microsoft.Extensions.DependencyInjection;   
using Microsoft.Extensions.Logging;   
using Sitecore.Framework.Runtime.Configuration;     

namespace Sitecore.Plugin.IdentityProvider.YourProvider   
{     
    public class ConfigureSitecore
    {           
        private readonly ILogger<ConfigureSitecore> _logger;           
        private readonly AppSettings _appSettings;             

        public ConfigureSitecore(ISitecoreConfiguration scConfig, ILogger<ConfigureSitecore> logger)           
        {               
            _logger = logger;               
            _appSettings = new AppSettings();               
            scConfig.GetSection(AppSettings.SectionName).Bind(_appSettings.YourProvider);           
        }             

        public void ConfigureServices(IServiceCollection services)           
        {               
            var provider = _appSettings.YourProvider;                 

            if (!provider.Enabled)               
            {                   
                return;               
            }                 

            _logger.LogDebug($"Configure '{provider.DisplayName}'. AuthenticationScheme = {provider.AuthenticationScheme}");

            new AuthenticationBuilder(services)                   
                .AddOpenIdConnect(provider.AuthenticationScheme, provider.DisplayName, options =>                   
                {                       
                    options.SignInScheme = "idsrv.external";                       
                    options.Authority = provider.Authority;                       
                    options.ClientId = provider.ClientId;                       
                    options.ClientSecret = provider.ClientSecret;                       
                    options.ResponseType = "code";                       
                    options.SaveTokens = true;                                              

                    options.Scope.Clear();                       
                    options.Scope.Add("openid");                       
                    options.Scope.Add("profile");                       
                    options.Scope.Add("email");                   
                });           
        }       
    }   
} 

  3. Register your subprovider in the configuration. The  {SI_server_root_folder}\sitecore\Sitecore.Plugin.IdentityProvider.AzureAd\Config\Sitecore.Plugin.IdentityProvider.AzureAd.xml file has an example of this.

    Example configuration XML

    RequestResponse
    <?xml version="1.0" encoding="utf-8"?>   
<Settings>     
    <Sitecore>       
        <ExternalIdentityProviders>         
            <IdentityProviders>           
                <YourProvider type="Sitecore.Plugin.IdentityProviders.IdentityProvider, Sitecore.Plugin.IdentityProviders">             
                    <AuthenticationScheme>IdS4-YourProvider</AuthenticationScheme>             
                    <DisplayName>Your Provider Name</DisplayName>             
                    <Enabled>true</Enabled>             
                    <Authority>https://your-provider.com</Authority>             
                    <ClaimsTransformations>               
                        <!-- Claims transformation rules here -->             
                    </ClaimsTransformations>           
                </YourProvider>         
            </IdentityProviders>       
        </ExternalIdentityProviders>     
    </Sitecore>   
</Settings>

  4. Optionally, register a subprovider in the Sitecore instance.

Register subproviders in the Sitecore instance

You can register the subprovider in the sitecore:federatedAuthentication:identityProviders configuration node in the Sitecore instance. The {application_root_folder}\App_Config\Sitecore\Owin.Authentication.IdentityServer\Sitecore.Owin.Authentication.IdentityServer.config file has an example of this.

Example in XML

RequestResponse
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">  
    <sitecore>    
        <federatedAuthentication>      
            <identityProviders>        
                <identityProvider id="YourProvider" type="Sitecore.Owin.Authentication.Configuration.DefaultIdentityProvider, Sitecore.Owin.Authentication">          
                    <param desc="name">$(id)</param>          
                    <param desc="domainManager" type="Sitecore.Abstractions.BaseDomainManager" resolve="true" />          
                    <caption>Your Provider Name</caption>          
                    <domain>extranet</domain>          
                    <transformations hint="list:AddTransformation">            
                        <transformation name="Name Transformation" type="Sitecore.Owin.Authentication.Services.DefaultTransformation, Sitecore.Owin.Authentication">              
                            <sources hint="raw:AddSource">                        
                                <claim name="name" />                  
                            </sources>              
                            <targets hint="raw:AddTarget">                
                                <claim name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />              
                            </targets>              
                            <keepSource>true</keepSource>            
                        </transformation>          
                    </transformations>        
                </identityProvider>      
            </identityProviders>    
        </federatedAuthentication>  
    </sitecore>
</configuration>

Configure claims transformations

You can configure claims transformations for each external identity provider. They are similar to what Sitecore already has, however, you have to have claims transformations on the SI server side for external identity providers to be able to use external claims in Sitecore Identity Server clients.

By default, Sitecore Identity operates with the following custom scopes: sitecore.profile as an identity resource and sitecore.profile.api as an API resource.

The sitecore.profile and sitecore.profile.api scopes both contain the following claims:

  • name

  • email

  • role

  • http://www.sitecore.net/identity/claims/isAdmin

To give users roles:

  • Map a particular incoming claim to the appropriate role claims. For example, to transform the 90e5a2e5-4e3f-4f25-8beb-1238052fda8e Azure AD group to the sitecore\Author role:

    RequestResponse
    <AzureGroupTransformation type="Sitecore.Plugin.IdentityProviders.DefaultClaimsTransformation, Sitecore.Plugin.IdentityProviders">
                <SourceClaims>
                                <Claim1 type="groups" value="90e5a2e5-4e3f-4f25-8beb-1238052fda8e" />
                </SourceClaims>
                <NewClaims>
                                <Claim1 type="role" value="sitecore\Author" />
                </NewClaims>
</AzureGroupTransformation>

To make a user an administrator:

  • Add http://www.sitecore.net/identity/claims/isAdmin and set the value to true (being an admin user in Sitecore is not about having a particular role). For example, to make all users from a9bb60b6-40d2-4e2a-88b8-0e47ee2d078e Azure AD group Sitecore administrator users:

    RequestResponse
    <AzureADUserToAdminUser type="Sitecore.Plugin.IdentityProviders.DefaultClaimsTransformation, Sitecore.Plugin.IdentityProviders">
                <SourceClaims>
                                <Claim1 type="groups" value="a9bb60b6-40d2-4e2a-88b8-0e47ee2d078e" />
                </SourceClaims>
                <NewClaims>
                                <Claim1 type="http://www.sitecore.net/identity/claims/isAdmin" value="true"/>
                </NewClaims>
</AzureADUserToAdminUser>

Then map the claim in Sitecore in the configuration:sitecore:federatedAuthentication:propertyInitializer:maps node.  The {application_root_folder}\App_Config\Sitecore\Owin.Authentication.IdentityServer\Sitecore.Owin.Authentication.IdentityServer.config file has an example of this:

RequestResponse
<federatedAuthentication>  
    <propertyInitializer>    
        <maps>      
                <map name="email" to="Email" />      
                <map name="name" to="FullName" />      
                <map name="http://www.sitecore.net/identity/claims/isAdmin" to="IsAdministrator" />    
        </maps>  
   </propertyInitializer>
</federatedAuthentication>

Use a similar procedure for the transformed name and email claims to map them to User properties in Sitecore.

The following example illustrates the necessity of having a mandatory claims transformation:

If a subprovider returns an identity with the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress claim, you cannot retrieve it in any SI client. You have two options:

  • Transform the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress claim to email on the SI server side so that SI server clients receive the email claim.

    RequestResponse
    <ClaimsTransformation type="Sitecore.Plugin.IdentityProviders.DefaultClaimsTransformation, Sitecore.Plugin.IdentityProviders">    
    <SourceClaims>      
        <Claim1 type="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />    
    </SourceClaims>    
    <NewClaims>      
        <Claim1 type="email" />    
    </NewClaims>  
</ClaimsTransformation>

  • Transform the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress claim to email in every SI client.

There are a number of limitations when Sitecore creates persistent users to represent external users. Sitecore does not support the following features for such users:

  1. Password management through Sitecore

  2. Modification of certain profile properties

  3. Changing a user password. You have to change passwords it in the corresponding identity provider.

Configure Azure AD

When you configure and use Azure AD with the Sitecore Identity server, you have to remember:

  • Check the ID tokens checkbox in the Advanced Settings in the Web - Authentication tab in the application registration.

  • Set the value of the groupMembershipClaims setting in the application manifest to ApplicationGroup.

  • You can only configure replyUrls in the legacy version of the application registration. Use replyUrlsWithType instead.

Do you have some feedback for us?

If you have suggestions for improving this article,