---
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 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](https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-openid-connect-code)

> [!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 Standard)* C# project.
    2. Create a `global.json` file at the root of the repository:

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

</details>

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

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.

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

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

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

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

</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 `SecurityGroup`.
- You can only configure `replyUrls` in the legacy version of the application registration. Use `replyUrlsWithType` instead.