---
title: "Use the Sitecore Identity server as a federation gateway"
slug: "use-the-sitecore-identity-server-as-a-federation-gateway"
abstract: "Sitecore Identity server can act as a gateway to external identity providers."
---
# Use the Sitecore Identity server as a federation gateway

Because it is based on [Duende IdentityServer](https://docs.duendesoftware.com/identityserver/v6), 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](https://docs.duendesoftware.com/identityserver/v6/ui/login/external/) 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](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc)

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

<details>
<summary><h2>Configure subproviders in the Sitecore Identity server</h2></summary>

To add a subprovider in the SI server:

1. Create a new plugin in Visual Studio:

    :::lettered
    1. Create a *Class Library* (.NET 8.0) C# project.
    2. Create a `global.json` file at the root of the repository:

        ```csharp
        {
            "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`:

        ```text
        <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#:

    ```csharp
    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

    ```xml
    <?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.

</details>

<details>
<summary><h2>Register subproviders in the Sitecore instance</h2></summary>

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

```xml
<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>

```

</details>

<details>
<summary><h2>Configure claims transformations</h2></summary>

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:

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

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

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

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

</details>

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