A Simple Guide to Setting up SSO with Azure AD Using Sitecore
Azure AD SSO in Sitecore in 5 steps.
With the introduction of the Identity Server in Sitecore, it has never been easier to implement various ways to configure how you sign into Sitecore. Single sign-on (SSO) is becoming more popular as it provides one set of credentials within an enterprise to not only provide access to a corporate resource, but also allows you to centrally manage permissions and security. In this guide, I will show you in five simple steps on how to set up SSO using Microsoft Azure Active Directory (AD).
Best of all, no coding required.
Yes, you heard it right, no coding required; don’t thank me, thank Sitecore. So without further ado, let’s dig in!
Requirements:
There are two requirements essentially needed:
1. Sitecore XP 9+ (I will be using 9.2 XP in this guide)
2. Microsoft Azure AD (if you/or your enterprise don’t have one, you can get a free trial for one year)
Some Things to Note:
I want to briefly provide some context on the default behavior of signing into Sitecore.
· When you navigate to your Sitecore instance URL you get redirected to the Identity Server
This is the default behavior; unless it is configured otherwise. The Sitecore URL used in this blog is the default: http://xp0.local.test. Take note of the URL that it gets redirected to; this is your identity server URL.
Note down the identity server URL as you will need it for this tutorial. In this case it is https://xp0-identityserver.local.test; however, yours may vary. You can simply go to IIS Manager and check the site binding for your identity server to get the URL as well:
Step 1: Peeking Inside the Configuration of Identity Server
In order for you to implement Azure AD SSO, we have to look into what needs to be changed. When I mentioned no code change, it was because Sitecore was generous enough to provide a configuration file within the Identity Server that can be edited to work specifically with Azure AD. It is in this file that you will make changes and add some values from Azure to make the magic happen:
· This file is called Sitecore.Plugin.IdentityProvider.AzureAd.xml
· To get to it, navigate to your Identity Server webroot/sitecore/Sitecore.Plugin.IdentityProvider.AzureAd/Config/
· Open the file by right clicking it and choosing a code editor, in this case I will be using Notepad++.
· Within this config file, we will need to modify the following:
1. Set the value for the <Enabled> setting to true: this will enable Identity Server to use this Azure AD as the Identity Provider.
2. Set values for <ClientId> and <TenantId> : these values will be retrieved from the app registration in your azure portal (covered later)
Step 2: Adding an App Registration in Azure AD
In order to use Azure AD you must have an App Registered in Azure AD. This is where you retrieve values for <ClientId> and <TenantId>. If you do not, don’t sweat it. I won’t make you click another link to follow another tutorial. This is how you will do that:
· Browse to Microsoft Azure portal, login and go into your Azure AD. You can navigate to the portal by clicking here.
· Go to your Azure AD and click on App Registrations on the left navigation pane:
· On the new page click on New App Registration
In the Register an application page:
· Type in a name for your App
· Keep the Supported account types default if you are setting up SSO for your organization only (default)
· For the Redirect URL, you will type in your Identity Server Site URL that was shown in the above Somethings to Note section; however, you will suffix it with a /signin-oidc at the end. Please see below:
· Click Register at the bottom. This will now register your application within your Azure AD.
Step 3: Configuring Identity Server Config File for Azure AD
Now with your app registered on Azure AD. We’re going to double check a few things on the app registration in Azure. We will then get the Client ID and Tenant ID and paste them to our config file for Identity Server.
In Azure, go to your new App Registrations and fine your new App Registration. In this demo this is called AzureSSODemo. In the overview page of your App Registration, you will find the client ID and tenant ID right on top. Copy and paste each one to its respective area in the Sitecore Identity Server Azure AD config file:
· Don’t forget to change the setting for <Enabled> to true
· Save the config file. Go into IIS Manager and recycle the App Pool for the Identity Server
· Now navigate to your Sitecore instance. Give it a few seconds but when it loads back up and redirects you to the Identity Server, you should now see an Azure AD button at the bottom:
Before you get tempted to click that new shiny button, we have one last step to cover.
Step 4: Adding User Transformations
We have everything set up and ready to go. However, we need to set one more configuration setting in the Identity Server Azure AD config file: user transformations. Identity Server does not recognize external accounts, so if you try and click to login through your Azure AD credentials, Identity Server will not know who you are in Sitecore and what role/permissions you have. It will then redirect you back to the Sitecore shell with a heartbreaking message stating that authentication has failed.
To solve this, we will set up a user group in Azure AD (if you don’t have one already) and we will use the Object ID of that user group and paste it in our Identity Server config file to set up a transformation.
Once again, Sitecore has provided us with a sample of such transformation at the bottom of the config file. We will simply use one of these samples. For the sake of simplicity, we will grab the AzureADUserToAdminUser transformation. Just copy it from the commented out samples towards the bottom of the config file under
<! — Transformation samples →:
· Copy this section without the comment tags
· Paste it right under Line 30. All that’s needed to be done is to copy over the Azure AD group/user object Id and replace the default value for claim1
· This step is only necessary if you don’t already have an Azure AD group you would like to use. If not, you will have to create one. Go back into your Azure portal and navigate into your Azure AD. On the menu to the left, click on Groups and then click New Group on top.
· Name the group whatever you would like for this demo I just used the name of the App Registration: AzureSSODemo. Keep all default settings and create the group. You can now assign Users from your Azure AD to this group. All users assigned to this group will be transformed in Sitecore Identity Server as Sitecore Admins.
· We will copy the Object Id of this group and paste it, replacing the default value setting in our Identity Server config transformation Claim1 Value. Save your changes to the file and recycle the Identity Server App pool once more.
Step 5: The Big Moment
Now that you have:
1. Enabled the Identity Server Azure AD configuration file
2. Added clientID / objectId for your app registration in Azure
3. Set up a transformation rule setting using a group object Id in Azure, it is now time to test it all out.
· Navigate to your Sitecore instance/shell. Again, once the page loads, you will see the Azure AD button. This time click it. You will be redirected to Microsoft’s login page:
· Enter your Microsoft account/Azure AD email and then your password. Click Sign In.
**You may be asked to stay signed in, it is up to you to make that call.**
· Finally, if everything was set up correctly, you will be redirected back to Sitecore and will be logged in:
Thank you for reading this blog and I hope to find this tutorial helpful for you and your company.
If so PLEASE FOLLOW for more great tutorials 🙏😊
Nabeel A.
Senior Software Engineer
Sitecore XP Solutions 9.2–9.3 Certified | Sitecore XC 9.2 Certified
dotnet Enthusiast
