Use the Sitecore Identity server as a federation gateway

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:

      {
          "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.

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

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.

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.

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:

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

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

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