Integrating Federated Authentication for Sitecore 9 with Azure AD


Federated Authentication Overview

Federated authentication allows members of one organization to use their authentication credentials (user name and password/security key) to access their corporate applications or any third party applications/services.

Organizations wishing to implement federate authentication with another organization require them to trust what each other has to say about user identities. Basically there should be a trust relationship between two parties.

In any federated identity management transaction, there are always three actors involved: the subject or user, the identity provider (IDP), and the Service Provider (SP) or Relying Party (RP). In our context the actors are as below.

Subject/User (Sitecore User): Subjects are the users who wish to access the resources of an organization using federated authentication/SSO.

Identity Provider (Azure AD): Identity providers are those parties that authenticate users and issue token/claims to the relying party (SP).

Service Provider (Sitecore XP):  Service providers are those parties that provide services to users based on the authentication events that occur between the IDP and the user.

In the context of Azure AD federated authentication for Sitecore, Azure AD (IDP/STS) issues claims and gives each claim one or more values. Sitecore reads the claims issued for an authenticated user during the external authentication process and allow access to perform Sitecore operations based on the role claim.

There are 2 parts involved in this integration as below

Part 1: Azure Active Directory setup/configuration

We need to first create an azure AD service using our Azure subscription, follow below steps to configure Azure AD service.

Step 1: Login to azure portal and click “New” and search for “Azure Active Directory” and click “Create” as shown below.

Azure Active Directory Service
Create Azure Active Directory

Step 2: Provide the basic information like “Organization name”, domain name, country and click Create button as shown in below screen shot.

Create Directory
Create Directory

Step 3: Go to your recently created Azure AD (xyz AD directory) and manage users like add user and create few groups representing your Sitecore roles e.g. Developer, Administrator, Content Author etc…

Manage users/roles
Manage users/roles

Step 4: Go to your directory and click “App registrations”, click “New application registration” and provide Service provider (your Sitecore instance) details as shown below.

Application Registration
Application Registration

Step 5:  Go to your application settings ( and preserve the Application ID show as below.

Application ID
Application ID

Step 6:  Update the application ( manifest file to change the default groupMembershipClaims property from null to SecurityGroup. This must be needed to send the group claims as part of the token as shown below.

Update Manifest
Update Manifest

With this step we have successfully completed Azure AD setup.  Next thing is we need to integrate Sitecore 9 with Azure AD, this can be done by adding/modifying few config files and it’s related code files to Sitecore solution to support OpenIdConnectAuthentication.

Part 2: Sitecore 9 Integration with Azure AD

Sitecore with Azure AD Authentication flow diagram

Azure AD OpenID Auth flow with Sitecore
Azure AD OpenID Auth flow with Sitecore

Step 1 : Open your Sitecore solution (to which you want to integrate Azure AD) with Visual studio and add an assembly Microsoft.Owin.Security.OpenIdConnect using nugget package manager.

OpenIdConnect Owin middleware
OpenIdConnect Owin middleware

Step 2 : EnableSitecore.Owin.Authentication.Enabler.config” file in App_Config\Include\Examples of your sitecore web site folder. [you just need to remove .example to enable the file].

Step 3: Add a new custom patch configuration file to include your federated authentication settings (App_Config\Include\Sitecore.Owin.AzureAD.Authentication.config) as below, you must need to change/replace the settings with your project related settings.

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:patch="" xmlns:role="">
  <sitecore role:require="Standalone or ContentDelivery or ContentManagement">
      <!-- Below settings describes your Azure AD settings -->
      <!-- you need to replace below client id with your azure application ID that we preserved from step 5 of Azure AD configuration -->
      <setting name="ClientId" value="78c48060-f0f6-4956-9e49-bdda03df656a" />
      <setting name="AADInstance" value="{0}" />
      <!-- you need to replace below Tenant with your azure AD domain which we created from step 2 of Azure AD configuration -->
      <setting name="Tenant" value="" />
      <!-- your Sitecore instance login url-->
      <setting name="PostLogoutRedirectURI" value="" />
      <!-- your Sitecore instance Url-->
      <setting name="RedirectURI" value="" />
        <!-- This is the custom processor that gets executed when azure AD posts the token to Sitecore -->
        <processor type="TechAspect.Sitecore.Authenticaton.AzureAD.Pipelines.AzureADIdentityProviderProcessor, TechAspect.Sitecore.Authenticaton" resolve="true" />
      <identityProviders hin="list:AddIdentityProvider">
        <identityProvider id="" type="Sitecore.Owin.Authentication.Configuration.DefaultIdentityProvider, Sitecore.Owin.Authentication">
          <param desc="name">$(id)</param>
          <param desc="domainManager" type="Sitecore.Abstractions.BaseDomainManager" resolve="true" />
          <caption>Sign-in with Azure Active Directory</caption>
          <transformations hint="list:AddTransformation">
            <!-- you need to have and Idp Claim for this to work -->
            <transformation name="Idp Claim" ref="federatedAuthentication/sharedTransformations/setIdpClaim" />
            <!-- This is to transform your Azure group into Sitecore Role. The claim value below is the object id of the role that needs to be copied from Azure -->
            <transformation name="devRole" type="Sitecore.Owin.Authentication.Services.DefaultTransformation, Sitecore.Owin.Authentication">
              <sources hint="raw:AddSource">
                <claim name="groups" value="e39ae6bb-78d6-4d47-bd2b-982cd2e4de3b" />
              <targets hint="raw:AddTarget">
                <claim name="" value="Sitecore\Tester" />
      <!-- Property initializer assigns claim values to sitecore user properties -->
      <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">
            <data hint="raw:AddData">
              <!--claim name-->
              <source name="" />
              <!--property name-->
              <target name="Email" />
          <map name="Name claim" type="Sitecore.Owin.Authentication.Services.DefaultClaimToPropertyMapper, Sitecore.Owin.Authentication">
            <data hint="raw:AddData">
              <!--claim name-->
              <source name="" />
              <!--property name-->
              <target name="Name" />
        <mapEntry name="all" type="Sitecore.Owin.Authentication.Collections.IdentityProvidersPerSitesMapEntry, Sitecore.Owin.Authentication">
          <sites hint="list">
          <!-- Registered identity providers for above providers -->
          <identityProviders hint="list:AddIdentityProvider">
            <identityProvider ref="federatedAuthentication/identityProviders/identityProvider[@id='']" />
          <!-- ExternalUserBuilder is what creates a user with customusername in Sitecore and assigns roles based on claim transformation configured above -->
          <externalUserBuilder type="Sitecore.Owin.Authentication.Services.DefaultExternalUserBuilder, Sitecore.Owin.Authentication">
            <param desc="isPersistentUser">true</param>

Step 4 : Add below TechAspect.Sitecore.Authenticaton.AzureAD.Pipelines.AzureADIdentityProviderProcessor processor to the Sitecore solution.

using Owin;
using Sitecore.Configuration;
using Sitecore.Diagnostics;
using Sitecore.Owin.Authentication.Configuration;
using Sitecore.Owin.Authentication.Pipelines.IdentityProviders;
using Sitecore.Owin.Authentication.Services;
using System.Globalization;
using System.Threading.Tasks;
using Microsoft.Owin.Security;
using Microsoft.Owin.Security.OpenIdConnect;

namespace TechAspect.Sitecore.Authenticaton.AzureAD.Pipelines
    public class AzureADIdentityProviderProcessor : IdentityProvidersProcessor
        public CustomIdentityProviderProcessor(FederatedAuthenticationConfiguration federatedAuthenticationConfiguration)
            : base(federatedAuthenticationConfiguration)

        protected override string IdentityProviderName
            get { return ""; }
        protected override void ProcessCore(IdentityProvidersArgs args)
            Assert.ArgumentNotNull(args, nameof(args));

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

            string aadInstance = Settings.GetSetting("AADInstance");
            string tenant = Settings.GetSetting("Tenant");
            string clientId = Settings.GetSetting("ClientId");
            string postLogoutRedirectURI = Settings.GetSetting("PostLogoutRedirectURI");
            string redirectURI = Settings.GetSetting("RedirectURI");

            string authority = string.Format(CultureInfo.InvariantCulture, aadInstance, tenant);
            args.App.UseOpenIdConnectAuthentication(new OpenIdConnectAuthenticationOptions
                Caption = identityProvider.Caption,
                AuthenticationType = authenticationType,
                AuthenticationMode = AuthenticationMode.Passive,
                ClientId = clientId,
                Authority = authority,
                PostLogoutRedirectUri = postLogoutRedirectURI,
                RedirectUri = redirectURI,

                Notifications = new OpenIdConnectAuthenticationNotifications

                    SecurityTokenValidated = notification =>
                        var identity = notification.AuthenticationTicket.Identity;

                        foreach (var claimTransformationService in identityProvider.Transformations)
                                new TransformationContext(FederatedAuthenticationConfiguration, identityProvider));


                        notification.AuthenticationTicket = new AuthenticationTicket(identity, notification.AuthenticationTicket.Properties);

                        return Task.FromResult(0);


Step 5 : We are done with the code and configuration changes, finally we need to build the solution and deploy the respective config and DLL files to Sitecore application folder.

Conclusion: Once the Sitecore instance is up and running, you will be able to see “Sign-in with Azure Active Directory” button below the Sitecore standard login panel as below. once you click the button, you will be presented with Microsoft portal login page, from there you need to provide valid Azure AD credentials to login into configured Sitecore instance.

Note: New Sitecore user will be created if the AD user is not exist in the Sitecore.

Login page

Microsoft login page

After successfully login, user will be routed to Sitecore home page as shown below.

Sitecore home

Important Points to recap:

1) Create an Azure AD service and register for new application from azure portal.

2) Manage AD service user/groups

3) Change the manifest information as mentioned in the step 6

4) Enable Sitecore.Owin.Authentication.Enabler.config

5) Add patch config file and custom processor (TechAspect.Sitecore.Authenticaton.AzureAD.Pipelines.AzureADIdentityProviderProcessor)

Reference blogs:

About The Author

One comment

  1. September 15, 2018 at 12:24 am

    Nice post. I learn something totally new and challenging on sites I stumbleupon on a daily basis.

    It’s always useful to read content from other authors and use a little something from other

Leave a Reply