Sitecore Identity, Federated Authentication and Federation Gateway

If you are already familiar with the differences between Sitecore Federated Authentication with Sitecore Identity VS Sitecore Identity as a Federation Gateway, please skip to the next section. Otherwise, it's essential to understand the differences as they are consistently being mixed up.

Sitecore uses OpenID Connect, so some of the terms are from OpenID Connect 1.0 and OAuth 2.0 - because OpenID Connect extends OAuth. I recommend having some reading if they are also new to you.

  1. To have Federated Authentication with Sitecore, we need to have an Identity Provider.
  2. Sitecore Identity Server is the out of the box Identity Provider that's set up with Sitecore shell site to provide Federated Authentication.
  3. There are two options when integrating a new Identity Provider
    1. Setup the new Identity Provider with Sitecore directly for Federated Authentication
    2. Setup the new Identity Provider with Sitecore Identity where Sitecore Identity act as a Federation Gateway. In this case, Sitecore still has Sitecore Identity Server as the Identity Provider.

What do those two options look like?
  1. External Identity provider directly setup with Sitecore for Federated Authentication:
    1. This option is more suitable for public websites which mean users come to Sitecore sites and are redirected to the external Identity Provider to login and then are redirected back to Sitecore sites.
    2. Sitecore client (shell) can keep on using Sitecore Identity Server. Both can stay behind DMZ if required.
  2. Sitecore Identity Server as the Federation Gateway to external Identity Providers:
    1. This option is more suitable for allowing Sitecore users (like authors) to log in to Sitecore client via external Identity providers.
    2. If this option is selected for websites, Sitecore Identity Server must be exposed to the Internet.

There are other differences, won't go into too much detail here. But hopefully, this gives you a good overview of Federated Authentication in the new Sitecore versions.

This post will be about option 1 - Sitecore Website Federated Authentication with Azure AD B2C. If you are interested in Option 2, which is set up Azure AD B2C with Sitecore Identity, Jason has created an excellent article about this already: Azure AD B2C with Sitecore Identity. He also provided a lot of help when I did this post 🙂

Sitecore Website Federated Authentication with Azure AD B2C

The Sitecore version used in this is 9.3.0. Here are the steps:

  1. Have an Azure AD B2C instance ready.
  2. Register a new App in Azure AD B2C. Collect the following information:
AD Tenant Name:
Application (Client) ID: xxxxxx-fe0f-4c1a-8101-xxxxxxxx
  1. Create a User Flow Policy of Type "Sign up and sign in". Collect the following information
Custom User Flow Name: B2C_1_signupsignin
  1. You can test accessing the below URL to make sure your AD B2C OpenID Connect endpoint is up. This is where you can see all your possible claims too.
  1. Please make sure the Sitecore instance has OWIN and Federated Authentication both enabled. Then there are three steps:
    • Setup an Asp.Net project. Below are some main Nuget packages you will need.
  <package id="Microsoft.IdentityModel.Protocols.OpenIdConnect" version="5.2.2" targetFramework="net472" />
  <package id="Microsoft.IdentityModel.Tokens" version="5.2.2" targetFramework="net472" />
  <package id="Microsoft.Owin" version="4.0.0" targetFramework="net472" />
  <package id="Microsoft.Owin.Security" version="4.0.0" targetFramework="net472" />
  <package id="Microsoft.Owin.Security.OpenIdConnect" version="4.0.0" targetFramework="net472" /> 
  <package id="Owin" version="1.0" targetFramework="net472" />
  <package id="Sitecore.Kernel" version="9.3.0" targetFramework="net472" />
  <package id="Sitecore.Mvc" version="9.3.0" targetFramework="net472" />
  <package id="Sitecore.Mvc.Analytics" version="9.3.0" targetFramework="net472" />
  <package id="Sitecore.Owin.Authentication" version="9.3.0" targetFramework="net472" />
    • Create a custom IdentityProvidersProcessor that inherits 
    • Below is a simple implementation that works
using Microsoft.IdentityModel.Tokens;
using Microsoft.Owin.Infrastructure;
using Microsoft.Owin.Security;
using Microsoft.Owin.Security.OpenIdConnect;
using Owin;
using Sitecore.Abstractions;
using Sitecore.Diagnostics;
using Sitecore.Owin.Authentication.Configuration;
using Sitecore.Owin.Authentication.Extensions;
using Sitecore.Owin.Authentication.Pipelines.IdentityProviders;
using Sitecore.Owin.Authentication.Services;
using System.Threading.Tasks;

namespace AzureB2CSitecoreFederated.Pipelines
    public class AzureB2C : IdentityProvidersProcessor
        public AzureB2C(FederatedAuthenticationConfiguration federatedAuthenticationConfiguration,
                        ICookieManager cookieManager,
                        BaseSettings settings)
                        : base(federatedAuthenticationConfiguration, cookieManager, settings)

        protected override string IdentityProviderName => "AzureB2C";

        protected override void ProcessCore(IdentityProvidersArgs args)
            Assert.ArgumentNotNull(args, nameof(args));

            var identityProvider = GetIdentityProvider();
            var authenticationType = GetAuthenticationType();

            string tenant = Settings.GetSetting("Sitecore.Feature.Accounts.AzureB2C.Tenant");
            string signupsigninpolicy = Settings.GetSetting("Sitecore.Feature.Accounts.AzureB2C.Policy");
            string clientId = Settings.GetSetting("Sitecore.Feature.Accounts.AzureB2C.ClientId");
            string aadInstanceraw = Settings.GetSetting("Sitecore.Feature.Accounts.AzureB2C.AadInstance");
            var aadInstance = string.Format(aadInstanceraw, tenant, signupsigninpolicy);
            var metaAddress = $"{aadInstance}/v2.0/.well-known/openid-configuration";
            var redirectUri = Settings.GetSetting("Sitecore.Feature.Accounts.AzureB2C.RedirectUri");
            var options = new OpenIdConnectAuthenticationOptions(authenticationType)
                Caption = identityProvider.Caption,
                AuthenticationMode = AuthenticationMode.Passive,
                RedirectUri = redirectUri,
                ClientId = clientId,
                Authority = aadInstance,
                MetadataAddress = metaAddress,
                UseTokenLifetime = true,
                TokenValidationParameters = new TokenValidationParameters() { NameClaimType = "name" },

                Notifications = new OpenIdConnectAuthenticationNotifications
                    SecurityTokenValidated = context =>
                        // Note 1 ------------------------- Please see after all steps
                        var debugClaims = context.AuthenticationTicket.Identity?.Claims;
                        context.AuthenticationTicket.Identity.ApplyClaimsTransformations(new TransformationContext(this.FederatedAuthenticationConfiguration, identityProvider));
                        return Task.CompletedTask; 

    • Then create a config file like below. Note the collected information are populated in the settings
<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="" xmlns:role="">
  <sitecore role:require="Standalone or ContentDelivery or ContentManagement">
      <setting name="Sitecore.Feature.Accounts.AzureB2C.Tenant" value="" />
      <setting name="Sitecore.Feature.Accounts.AzureB2C.Policy" value="B2C_1_signupsignin" />
      <setting name="Sitecore.Feature.Accounts.AzureB2C.ClientId" value="xxxxxx-fe0f-4c1a-8101-xxxxxxxx" />
      <setting name="Sitecore.Feature.Accounts.AzureB2C.AadInstance" value="{0}/{1}" />
      <setting name="Sitecore.Feature.Accounts.AzureB2C.RedirectUri" value="" />

        <processor type="AzureB2CSitecoreFederated.Pipelines.AzureB2C, AzureB2CSitecoreFederated" resolve="true" />

    <federatedAuthentication type="Sitecore.Owin.Authentication.Configuration.FederatedAuthenticationConfiguration, Sitecore.Owin.Authentication">
      <identityProvidersPerSites hint="list:AddIdentityProvidersPerSites">
        <mapEntry name="Azure AD B2C for website" type="Sitecore.Owin.Authentication.Collections.IdentityProvidersPerSitesMapEntry, Sitecore.Owin.Authentication" resolve="true">
          <sites hint="list">
          <identityProviders hint="list:AddIdentityProvider">
            <identityProvider ref="federatedAuthentication/identityProviders/identityProvider[@id='AzureB2C']" />
          <externalUserBuilder type="Sitecore.Owin.Authentication.Services.DefaultExternalUserBuilder, Sitecore.Owin.Authentication" resolve="true">
            <!-- Note 2 ------------------------- Please see after all steps -->

      <identityProviders hint="list:AddIdentityProvider">
        <identityProvider id="AzureB2C" type="Sitecore.Owin.Authentication.Configuration.DefaultIdentityProvider, Sitecore.Owin.Authentication">
          <param desc="name">AzureB2C</param>
          <param desc="domainManager" type="Sitecore.Abstractions.BaseDomainManager" resolve="true" />
          <transformations hint="list:AddTransformation">
            <!-- Note 3 ------------------------- Please see after all steps -->
            <transformation type="Sitecore.Owin.Authentication.Services.DefaultTransformation, Sitecore.Owin.Authentication">
              <sources hint="raw:AddSource">
                <claim name="jobTitle" value="SomeRoleText" />
              <targets hint="raw:AddTarget">
                <claim name="" value="CustomDomain\SomeRole" />


      <!-- Note 4 ------------------------- Please see after all steps -->
      <propertyInitializer type="Sitecore.Owin.Authentication.Services.PropertyInitializer, Sitecore.Owin.Authentication">
        <maps hint="list">
          <map name="email claim" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication" resolve="true">
            <data hint="raw:AddData">
              <source name="emails" />
              <target name="Email" />
          <map name="full_name" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication" resolve="true">
            <data hint="raw:AddData">
              <source name="name" />
              <target name="FullName" />
          <map name="first_name" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication" resolve="true">
            <data hint="raw:AddData">
              <source name="" />
              <target name="FirstName" />
          <map name="last_name" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication" resolve="true">
            <data hint="raw:AddData">
              <source name="" />
              <target name="LastName" />
          <map name="streetAddress" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication" resolve="true">
            <data hint="raw:AddData">
              <source name="streetAddress" />
              <target name="AddressProp" />

Note that the integration is using the new endpoints of Azure AD B2C, not since it will be deprecated by the end of 2020. More details here:

Also please see the notes in the code and config files (For example, can search "Note 1" on the page to find its location in the demo code/configs)
  • Note 1:  This section of code is required so this custom Identity Provider Processor picks up the shared transforms that are set up out of the box by Sitecore. One of which is the "idp" claim. If you do not have this section, very likely you can get the error "idp claim is missing". Having sharedTransformations/setIdpClaim section does not have any effort on your custom identity provider if it doesn't even try to apply shared transformations.
  • Note 2:  You can choose to persist users or having virtual users. I had virtual users in this demo. 
  • Note 3:  Azure AD B2C has a limitation that it doesn't pass group information in the claims. There are ways to customize the AD side to enable the claim however in this demo it just mapped to some claims and picked up some value to map roles in Sitecore. It could be enough for most use cases.
  • Note 4:  You can also map user profile properties, these are some examples.

Login Link

Since this is a website, by default you have no way to test this integration. You can set up a custom page to generate the login link to test the integration:

In the controller:
using Sitecore.Abstractions;
using System.Linq;
using System.Web.Mvc;

namespace AzureB2CSitecoreFederated.Controllers
    public class FederatedLoginController : Controller
        private readonly BaseCorePipelineManager _pipelineManager;
        public FederatedLoginController(BaseCorePipelineManager pipelineManager)
            _pipelineManager = pipelineManager;

        public ActionResult Index()
            var args = new Sitecore.Pipelines.GetSignInUrlInfo.GetSignInUrlInfoArgs("website", "/");
            Sitecore.Pipelines.GetSignInUrlInfo.GetSignInUrlInfoPipeline.Run(_pipelineManager, args);
            ViewBag.SignInUrl = args.Result.FirstOrDefault()?.Href;
            return View();

In the views
@using System.Web.Mvc;

@{using (Html.BeginForm(null, null, FormMethod.Post, new { action = ViewBag.SignInUrl }))
        <button type="submit">

    <p>Is Authed: @Sitecore.Context.User.IsAuthenticated</p>
    <p>Name: @Sitecore.Context.User.Name</p>
    <p>Localname: @Sitecore.Context.User.LocalName</p>
    <p>Domain: @Sitecore.Context.User.GetDomainName()</p>
    <p>Profile Email: @Sitecore.Context.User.Profile.Email</p>
        @Newtonsoft.Json.JsonConvert.SerializeObject(Sitecore.Context.User, Newtonsoft.Json.Formatting.Indented, new Newtonsoft.Json.JsonSerializerSettings
      ReferenceLoopHandling = Newtonsoft.Json.ReferenceLoopHandling.Ignore

Skipped classes and configs for registering dependencies, you know how to do them. 

That is all. In general, it's a pretty easy setup, always check logs and URL requests to identify issues and errors.