Use the Sitecore Identity server as a federation gateway

Version: 9.3

Because it is based on the IdentityServer4, 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).  IdentityServer4 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 Standard) C# project.

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

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

      Specify the version as appropriate.

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

    4. Add other references you need: Sitecore.Framework.Runtime.Commands to enable commands, Sitecore.Framework.Runtime.Abstractions to enable using runtime abstractions, and references to other plugins if you build on features already in a plugin.

  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, you must have an object of the Microsoft.AspNetCore.Authentication.AuthenticationBuilder type . Use new Microsoft.AspNetCore.Authentication.AuthenticationBuilder(services) instead of services.AddAuthentication() in your plugin.

  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.

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

Register subproviders in the Sitecore instance

By default, the Sitecore instance knows only about one external identity provider: the  SI server (the SitecoreIdentityServer name in the Sitecore.Owin.Authentication.IdentityServer.config configuration file) and it does not know about any subproviders unless you explicitly specify them.

You specify subproviders in the following situations:

  • You want to map the subprovider to other sites instead of the SitecoreIdentityServer itself. For example, the SI server is mapped to the shell and admin sites, but you want to map the Azure AD provider configured in the SI server to the website.

  • You use the GetSignInUrlInfoPipeline pipeline and you want to get a sign-in URL for a particular subprovider to  redirect users directly to the subprovider login page (skipping the SI login page).

Note

It is optional to register subproviders in Sitecore in order to use the new login endpoint with subproviders. If you enable the built-in Azure AD subprovider in the SI server, and then specify this URL $(loginPath)shell/SitecoreIdentityServer/IdS4-AzureAd in the loginPage attribute of a shell site, shell users can authenticate using Azure AD and skip the SI server login page

To register Azure AD in the SI server, specify the value of the AuthenticationScheme  setting as  IdS4-AzureAd.

To register a subprovider in Sitecore: 

  • Add an identityProvider node in the sitecore/federatedAuthentication/identityProviders node. This configuration node must follow the naming conventions for the name parameter. The name parameter must be in this format: [gateway_identity_provider]/[AuthenticationScheme], where gateway_identity_provider is an identity provider that Sitecore communicates with directly, and AuthenticationScheme is an authentication scheme of a subidentity provider you have configured in gateway_identity_provider (for example, IdS4-AzureAd).

    There are a number of limitations to take into account:

    • The TriggerExternalSignOut and Transformations properties are inherited from the gateway_identity_provider node and you cannot override them.

    • The Enabled property of the gateway_identity_provider provider must be set to Enabled to enable this subprovider.

The App_Config\Sitecore\Owin.Authentication.IdentityServer\Sitecore.Owin.Authentication.IdentityServer.config configuration file has an example of registering Azure AD subprovider.

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 the  following reasons:

  • There are no Sitecore instances in the communication between the SI server and other SI clients (those that are not Sitecore itself). For instance, if some non-Sitecore application uses the SI server as an external provider, that application will not receive normalized claims unless they are normalized in SI server.

  • The SI server returns only those claims that were actually requested by SI clients using Scopes. Therefore, SI clients will not receive claims that are unknown to them.

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

Note

You can modify requested scopes for Sitecore in this pipeline: sitecore/pipelines/owin.identityProviders/processor[id=SitecoreIdentityServer]/scopes).

 For applications that use the Sitecore.Plugin.Authentication.OpenIdConnect package, check the {application_root_folder}\sitecore\Sitecore.Plugin.Authentication.OpenIdConnect\Config\openIdConnect.xml file. The configuration path is Sitecore:Authentication:OpenIdConnectOptions:Scope:....

Note

You can find default scope definitions in the {SI_server_root_folder}\sitecore\Sitecore.Plugin.IdentityServer\Config\identityserver.xml file.

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

  • name

  • email

  • role

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

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

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>
    
Note

Do not add multiple nodes with the same name. If you need multiple nodes, name the nodes AzureGroupTransformation1, AzureGroupTransformation2, and so forth.

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
<propertyInitializer>
    <maps>
        <map name="set IsAdministrator" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication">
            <data hint="raw:AddData">
                <source name="http://www.sitecore.net/identity/claims/isAdmin" value="true" />
                <target name="IsAdministrator" value="true" />
            </data>
        </map>
    </maps>
</propertyInitializer>

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:

  • In the SI server, you can add  a claims transformation to map http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress to an  email claim. See the example in the {SI_server_root_folder}\sitecore\Sitecore.Plugin.IdentityProvider.AzureAd\Config\Sitecore.Plugin.IdentityProvider.AzureAd.xml file.

  • Register a new scope with the necessary claims in the SI server, allow the client to request this scope, and request this scope by the 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. Reading and deleting roles of external users in the User Manager because these roles are not stored in Sitecore.

  2. Because of this, using the Access Viewer.

  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 SecurityGroup.

  • 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,