Azure AD in Sitecore in 5 Simple 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!
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:
- When you navigate to your Sitecore instance URL you get redirected to the Identity Server
Sitecore Shell redirect to 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:
- This file is called:
- To get to it, navigate to your Identity Server
Navigate to Sitecore.Plugin.IdentityProvider.AzureAd.xml
- Open the file by right clicking it and choosing a code editor, in this case I will be using Notepad++.
Right click and edit the config file with a code editor.
- 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)
The settings that will need to be changed in order to integrate Azure AD.
- 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:
Left menu pane on Azure Portal
- On the new page click on New App Registration
Add new app registration in Azure
- 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:
Add the Identity Server URL with a “/signin-oidc” suffixed at the end
- Click Register at the bottom. This will now register your application within your Azure AD.
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:
Copy the Client ID and Object ID from your new App Registration
- 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
Recycle Identity Server App pool
- 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:
Login through Azure AD button now present
Before you get tempted to click that new shiny button, we have one last step to cover.
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
AzureAD User to Sitecore Admin Transformation claim
- 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.
Copy/paste the new group Object Id into the transformation claim
- Enabled the Identity Server Azure AD configuration file
- Added clientID / objectId for your app registration in Azure
- 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:
Redirected to Microsoft login
- 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.
- Nabeel Afsar