Sitecore Identity Server

In this four part series of blog posts, we will examine in detail the Sitecore Host platform and what benefits this brings to Sitecore Experience Platform. We will also have a closer look at Sitecore Host Applications as well as the Sitecore Host plugins. I will encourage you to please read through these blog posts starting with part one, through part four. I have also provided links below if you would like to jump and have a peek on the other parts as well. All code snippets referenced in the blog posts can also be found on my public Github repo using the link provided below.

1. Sitecore Host part one – Introduction to Sitecore Host, Sitecore Host applications and Sitecore Plugins
2. Sitecore Host part two – Sitecore Horizon 9.3
3. Sitecore Host part three – Sitecore Identity Server (this post)
4. Sitecore Host part four – Creating and extending Sitecore Host Plugins
5. Code samples in my Github Repository

What is Sitecore Identity Server?

Sitecore Identity Server is a mechanism to log in Sitecore for both Sitecore Users & External Users

Key Highlights

• Introduced in Sitecore 9.1 and it builds on Federated Authentication introduced in Sitecore 9.0
• It is based on IdentityServer4 which is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core
• Acts as a federation gateway to configure multiple identity providers
• As a federation gateway, this enables developers to focus on customization. This means IdentityServer can be customized to fit your Your developers can write code to adapt into what makes sense in your scenarios
• In Sitecore 9.1 and later, Sitecore Identity enabled by default

• The identityserver–contrib-membership package allows ASP.NET 2.0 Membership database to be used as an IdentityServer user store

Enabling Azure Active Directory (AzureAd) Identity Provider

By default, IdentityServer comes with AzureAd Identity Provider that is disabled. You can enable this provider using the following steps.

1. Locate the Sitecore.Plugin.IdentityProvider.AzureAd plugin on your IndentityServer instance as shown in screenshot below:

Open and edit the Sitecore.Plugin.IdentityProvider.AzureAd.xml config file and supply the values as follows 

1. DisplayName – specify the caption of the login button, for example “Login with Azure AD”
2. Enabled – set this to true
3. ClientId – specify your Azure registered Application ID. More guidance about this is provided later in this blog
4. TenantId – specify your Azure Tenant ID for your registered application. More guidance about this is provided later in this blog
5. ClaimsTransformations – specify claim mappings of AzureAd source claims to Sitecore Identify normalised claims. As a federation gateway, IdentitySever shields your client applications from the complexities of external providers by performing a claim transformation to what Identify server has control over.

Configuring Claims Transformations

By default, Sitecore Identity operates with the following custom scopes: sitecore.profile as an identity resource and sitecore.profile.api as an API resource.

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

The screenshot below shows examples of mapping AzureAd specific claims into normalised claims above in IdentityServer

To give users roles:

• Map a particular incoming claim to the appropriate role claims. The above screenshot shows an example of transforming the 8b0acd88-5eaf-4776-a637-d2952f2321ae Azure AD group to the sitecore\Developer role role

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). The screenshot above shows an example of making all users from f30226fc-16e1-4d7e-bf5d-2f4b8df553aa Azure AD group into Sitecore Administrator users

Mapping the IdentityServer normalised claims into Sitecore

Normalised claims are mapped into Sitecore using the configuration: sitecore:federatedAuthentication:propertyInitializer:maps node.

The {Sitecore_Instance_Root_Folder}\App_Config\Sitecore\Owin.Authentication.IdentityServer\Sitecore.Owin.Authentication.IdentityServer.config file has an example of this, as shown below:

As shown above there are mappings into IsAdministrator, Email and FullName

Configuring Azure AD Client on Azure Portal

Follow steps from Microsoft on authorizing access to web applications using OpenId Connect and Azure AD

Testing AzureAd External Provider End-to-End

If you have configured everything as expected, then you should see an additional login button on your IdentityServer login page as shown below

Clicking on the “Azure AD” button will redirect you to the AzureAd login page, from which you can then login with your AzureAd users

Sitecore user name generation

Once successfully logged in via AzureAd external provider, you should have this user persisted within Sitecore User Manager. The screenshot below shows a sample user from AzureAd

User names must be unique across a Sitecore instance. You cannot use user names from different external providers as Sitecore user names because this does not guarantee that the user names are unique.

The DefaultExternalUserBuilder class creates a sequence of user names for a given external user name. It then uses the first of these names that does not already exist in Sitecore. The values in the sequence depend only on the external username and the Sitecore domain configured for the given identity provider.

Should you choose to customise your user names, you can provide your own implementation, such as the one suggested in Sitecore.StackExchange.com

Please note the default implementation is provided in Sitecore.Owin.Authentication.dll

Then you will need to register your custom implementation within the configuration file {Sitecore_Instance_Root_Folder}\App_Config\Sitecore\Owin.Authentication\Sitecore.Owin.Authentication.config

Screenshot below shows what you need to change:

Claims mappings  troubleshooting using ASP.NET 2.0 Membership Tables

When performing end to end testing with your AzureAd external provider, you may come across issue with claim mappings into IdentityServer. The good news is that all the source claims originating from AzureAd are captured and stored in the Core database, within the ExternalUserData table, as shown in the screenshot below

Each external user successfully persisted will have an entry in this table, and the [Data] column has the JSON payload of their source claims, which looks like in the screenshot below

Ensure your IdentityServer claim mappings match those in this Json, otherwise your mapping will not work.

Conclusion

In this blog post, we examined what is Sitecore Identity Server in detail and explored the powerful feature of federation gateway. We also explored the default use case of Azure Active Directory and how to configure Sitecore Identity to work with Azure AD as external identity provider

In the fourth and final part of this four-part series, we will examine Creating and Extending Sitecore Host Plugins in detail. We will walk through creating a Sitecore Identity subprovider plugin for Active Directory Federation Services (ADFS)

Please feel free to leave us your feedback and/or comments below.

Introduction to Sitecore Host, Sitecore Host Applications and Sitecore Host Plugins

In this four part series of blog posts, we will examine in detail the Sitecore Host platform and what benefits this brings to Sitecore Experience Platform. We will also have a closer look at Sitecore Host Applications as well as the Sitecore Host plugins. I will encourage you to please read through these blog posts starting with part one, through to part four. I have also provided the links below if you would like to jump and have a peek on the other parts as well. All code snippets referenced in the blog posts can also be found on my public Github repo using the link provided below.

1. Sitecore Host part one – Introduction to Sitecore Host, Sitecore Host applications and Sitecore Plugins (this post)
2. Sitecore Host part two – Sitecore Horizon 9.3
3. Sitecore Host part three – Sitecore Identity Server
4. Sitecore Host part four – Creating and extending Sitecore Host Plugins
5. Code samples in my Github Repository

What is Sitecore Host

Sitecore Host in a new common platform for all Sitecore Services, that was introduced in Sitecore Experience Platform 9.1. Sitecore Host acts as a base for a Sitecore Service and it requires .NET Core runtime and hosting bundle 2.1

Sitecore Service is a feature or piece of functionality that runs separately outside of main Sitecore instance

One cool benefit that Sitecore Host provides is the pluggable nature of its architecture. This means the base Sitecore Services can be extended through Sitecore Host Plugins, without having to change or recompile any part of the base code.

What is Sitecore Host Plugin?

You can define a Sitecore Host Plugin as a feature or functionality that is dynamically loaded into Sitecore Host. As you will see later on, a plugin can contain Code, Configuration, Commands and Content. A plugin can also depend on another plugin, and therefore plugins are always loaded in a dependency order.

What is Sitecore Host Application?

Sitecore Host Application is therefore a fully hosted application that consists of the Sitecore Host base code plus one or more Sitecore Host plugins. It consists of the following parts: Root folder, Application Assets Folder, Sitecore folder and SitecoreRuntime folder.

Sitecore Host applications includes:

• Universal Tracker Service
• Sitecore Identity Server
• Sitecore Horizon 9.3

Sitecore Host Directory Structure

Root Folder

• All code libraries/DLLs including the  .NET Core runtime
• The Host DLL itself (E.g. Authoring.Host.dll)
• Optional configuration file for Sitecore Host itself (sitecore.xml)
• Optional environment-specific configurations, e.g. sitecore.production.xml for production environment

Application Assets Folder

• Contain the Sitecore Host Application Core assets such as Configuration files
• Content folders
• MVC views folders

Sitecore Folder

• Contains Sitecore Host plugin libraries supplied by Sitecore
• Contains the Sitecore Host plugin manifest files plus any additional assets such as configuration files

SitecoreRuntime Folder

• Special folder to extend or modify base Sitecore Host application
• Contains custom Sitecore Host plugins, such as those created by developers
• Each folder acts as a store for an environment
• Structure mirrors main Host application

Cross-platform support

In Windows environments, these applications are hosted as Internet Information Services (IIS) websites as the .NET Core hosting bundle comes with IIS Support. As .NET is cross-platform, these applications can be hosted using the Kestrel web server on Linux and macOS

Other Sitecore Host Benefits

Sitecore Host platform comes with many benefits to both the businesses as well as to the developers building cool stuff with Sitecore.

• Unified service registration and Dependency Injection
• Unified configuration system that is merged and patched the same way
• Unified file system access and directory structure
• Unified Command-line actions that work the same way for all applications
• Dynamically loaded plugins
• Cross-platform ready – the services behave the same way whether run on cloud or on-premises, in Windows, Linux or macOS workloads
• Installation experience is consistent

Conclusion

In this blog post, we examined what is Sitecore Host, Sitecore Host applications and their composition and directory structure. We also had an introduction to Sitecore Host plugins and the extensibility the framework introduces to Sitecore Host. We finished with some of the benefits Sitecore Host brings.

In the second part of this four-part series, we will examine Sitecore Horizon 9.3 one of the Sitecore Host Applications.

Please feel free to leave us your feedback and/or comments below.