Integrating Sitecore Identity with Azure AD on Kubernetes

Sitecore Identity (SI), introduced in Sitecore 9.1, is the single sign-on mechanism for any Sitecore instance (XM, XP, XC, …) that requires authentication.

As it was provided in a web deploy package (WDP), making small config changes like integrating with Azure AD was straightforward. With Sitecore moving to containers, and SI thus being provided as container image, making these same config changes becomes more complex… unless you’re willing to throw some Kubernetes features at it.

Sitecore Identity is an OpenID Connect compliant security token service (STS), based on IdentityServer4. Its default setup is an OAuth wrapper around good old Sitecore Membership:

Because it’s based on IdentityServer4, you can use SI as a gateway to one or more external identity providers (or subproviders, sometimes also called inner providers). For example, Azure AD:

This allows business users to log into Sitecore CM using their corporate (Azure AD) account.

Configuring SI to integrate with Azure AD is supported out-of-the-box. You need to

  1. Register Sitecore as an Application in your Azure AD tenant

  2. Create groups in your Azure AD for the users you want to give access to the Sitecore back-end

  3. Configure SI to connect to that Azure AD application and add a user mapping that specifies the role (e.g. Sitecore\admin) for a specified Azure AD group

You find the official documentation on Use the Sitecore Identity server as a federation gateway, but I recommend Setting Up Azure Active Directory Integration with Sitecore Identity Server / Sitecore 9.1 ( for a more detailed walkthrough of this setup.

Deploying SI with a Web Deploy Package

Before containers, changing the configuration was straightforward: SI is provided by Sitecore as a WDP (web deploy package — see Sitecore Downloads: Sitecore Identity 600). A structured folder containing DLLs, config XML files, … that you can deploy to IIS (virtual machine, Azure App Service, …) using Web Deploy.

Change the config files, deploy the updated package and you’re done.

Deploying SI with a container image

Next to WDP, SI is also provided as a container image. For example,

Compared to changing a WDP zip file, creating a custom container image requires more skills and infrastructure:

None of this is rocket science, but it’s quite some work to change a simple config file.

Configuring SI with Kubernetes ConfigMap

With the custom container image approach, you first copy modified files over an original image. Then these modifications are baked into a new image that you deploy to Kubernetes. Kubernetes uses an abstraction to run this image on actual hardware.

Thanks to the abstraction layer, it’s possible for Kubernetes to hijack the files an image tries to access while it’s running: in the id.yaml k8s spec file provided by Sitecore, you add a volumeMount, which tells the runtime that when image wants a file from /Identity/sitecore/Sitecore.Plugin.IdentityProvider.AzureAd/Config/ it should first be search in a volume called config. The config volume forwards this to a configMap called sitecore-id-azuread-config (an alternative would be an actual storage).

A Configmaps is an API object in Kubernetes used to store data in:

A ConfigMap allows you to decouple environment-specific configuration from your container images, so that your applications are easily portable.

In our case, we can simply put the whole custom configuration file in it:

With this setup it’s possible to run Sitecore’s official SI image with a custom Identity/sitecore/Sitecore.Plugin.IdentityProvider.AzureAd/Config/Sitecore.Plugin.IdentityProvider.AzureAd.xml file, containing your project specific Azure AD configuration. No need to create a custom image for it!

Tags: #kubernetes, #sitecoreidentity