Sitecore Host part three

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

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:

AzureAd-HostPugin-Location
AzureAd-HostPugin-Location
  • Open and edit the Sitecore.Plugin.IdentityProvider.AzureAd.xml config file and supply the values as follows 3.2 AzureAd-HostPugin-UpdateConfiguration
    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:

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

    AzureAd-ClaimTransformation
    AzureAd-ClaimTransformation

    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:

    Sitecore-Owin-Authentication-IdentityServer-Config
    Sitecore-Owin-Authentication-IdentityServer-Config

    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

    Azure AD subprovider
    Azure AD subprovider

    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

    Sitecore-Owin-Auth-ExternalUserNames
    Sitecore-Owin-Auth-ExternalUserNames

    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:

    Sitecore-Owin-Auth-DefaultExternalUserBuilder-Type-Registration
    Sitecore-Owin-Auth-DefaultExternalUserBuilder-Type-Registration

    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

    Asp.Net2.0Membership-ExternalUserDataTable
    Asp.Net2.0Membership-ExternalUserDataTable

    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

    Sitecore-Owin-Auth-ExternalUser-SourceClaims
    Sitecore-Owin-Auth-ExternalUser-SourceClaims

    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.

    6 thoughts on “Sitecore Host part three

    1. Pingback: Sitecore Host part two | 360AgileWeb
    2. Pingback: Sitecore Host part four | 360AgileWeb
    3. Pingback: Sitecore Host part one | 360AgileWeb
    4. Pingback: Doing my first Sitecore User Group UK Talk | 360AgileWeb
    5. Pingback: Doing my first Sitecore User Group talk | 360AgileWeb
    6. Pingback: Deprecated AD Module: Your upgrade options | 360AgileWeb

    Leave a Reply

    Fill in your details below or click an icon to log in:

    WordPress.com Logo

    You are commenting using your WordPress.com account. Log Out /  Change )

    Google photo

    You are commenting using your Google account. Log Out /  Change )

    Twitter picture

    You are commenting using your Twitter account. Log Out /  Change )

    Facebook photo

    You are commenting using your Facebook account. Log Out /  Change )

    Connecting to %s

    This site uses Akismet to reduce spam. Learn how your comment data is processed.