Securing Umbraco Backoffice with Azure Active Directory

date_range  26 April 2016


I’ve been creating a few Umbraco sites recently, some all for the same company and realised that it was rather mean to expect everyone to have to remember passwords for every single site they were administering. What would be great, I thought, was if they could all use a single sign on method and luckily I was using Azure to host these sites, so I had access to Azure Active Directory (AAD) which allows for 3rd party integrations using OAuth. Even more luckily there are a few Nuget packages out there to link the Umbraco backoffice to AAD but the documentation is scarce. I got this working by trying a few combinations of Stack Overflow posts but decided to share my solution here.

First off, create an ASP.Net app in Visual Studio and install Umbraco into. Get it all setup and create a local admin account for the Umbraco backoffice. By this I mean a normal account through the setup wizard. When entering the email address though, make sure it’s not the one linked to the Azure account you intend to authenticate with.

Then, you’re going to want to create an Application in your AAD. At the time of writing, the new Azure portal doesn’t have management for AAD so you’ll need to go to Now either create a new AAD or use an existing one (every Azure account has a Default Directory). Click on a directory then click Applications along the top. In the bottom task bar there should be an Add button, click that an this dialogue should appear.


You’re creating an application not one from the gallery so click the top option. The name is arbitrary but must be unique. Click the next arrow and you’ll be greeted by a second dialogue. Grab the address of your debugging URL from Visual Studio and wack umbraco on the end for the sign on URL. Then in the App ID Uri box, put the address again. This must be unique too which is why using the debugging address is a good idea as it should always be different. Now click the tick button and Azure will now register your integration application in your AAD. Once it’s complete, go to the Configure page and grab your Client ID and your Tennant ID. The later isn’t immediately obvious; if you click View Endpoints in the bottom toolbar, your Tennant ID is the GUID you see in all of the addresses.


Now we can go back to Visual Studio and add a few appSettings to the web.config file.

You’ll want them in there so you can override them with a XDT file when you deploy to a different environment. To do this you need to follow the above steps to create a new AAD Application and grab the ClientId and set the PostRedirectUrl parameters to the domain for the other environment. If you only have one environment then you don’t need to worry.

Next, install the following Nuget package:

Install-Package UmbracoCms.IdentityExtensions.AzureActiveDirectory

This dumps a few classes into your app_start directory in your project. Two of them we care about.

First off UmbracoADAuthExtensions.cs. There’s a lot of mess in there but you’ll want it to look something like this:

Most of this would look familiar if you’ve ever used Asp.Net Identity with any other single sign on provider; most of it is just setting up the OAuth options but there are a few Umbraco options in there that are mostly just for cosmetic things like icons on the Login page. The meaty part is the overload of the OpenIdConnectAuthenticationNotifications.AuthorizationCodeReceived property. The default one does quite well with regard to the fact that a new Umbraco user gets created, but the users Name isn’t all that pretty. This bit of code stolen from here.

Next you’ll want to update UmbracoOwinStandardStartup.cs. If for whatever reason you’re already using an Owin Startup, you’ll want to merge the following code in, otherwise make it look like this:

Boring isn’t it? It just calls the method we modified above, using configuration pulled from the appsettings we defined earlier.

Now rebuild the Umbraco project, fire it up and go the backoffice Url and you should have something like this:

Umbraco Login

Clicking the Sign In with Active Directory button redirects you to the Microsoft Azure sign in page. Enter your credentials and you’ll be redirected back to the Umbraco back office. If you used the same email address for the normal Umbraco account as you did for your Azure account, you’ll get an error message saying this user already exists and you should link the user. If you login with this account you can click the user link in the top left hand corner, you should see the view below which you can click and associate the user to the email address.

Umbraco Link

comments powered by Disqus

chevron_left Archive