Configure Umbraco to use Azure AD for Back Office user authentication

Authentication In Umbraco

Umbraco CMS (v7.9.2) features a well known and standard username/password scenario for handling authentication. This can be fine but corporate Umbraco adapters would probably not be to happy when we ask them to remember one more password as well as giving up centralized user account management.

Corporations who’s IT is Microsoft based will often have security matters handled by Active Directory – and if taking IT serious these days –  have Federation Services configured and synchronization with Azure Active Directory in place.

I wrote a post regarding the business value and importance of SSO when using Umbraco in a Microsoft infrastructure based on Azure here.

When Umbraco CMS is added to the Corporate Azure mix – corporations will require or rather should require that matters of Authentication should be handled by Azure Active Directory.

This post  is a tutorial on how to make this setup work in practice. Its easy ones you invested  hours on making all the pieces fit – and here is what I have learned, so that you don’t have to.

No plug and play solution found

I was unable to find a “plug and play” solution that enables Azure AD authentication for Umbraco Back Office Users. I might be wrong – so please send me a comment if that is the case.

Existing official Solution

There is some documentation to be found in the configuration files when  Umbraco is installed and the  Umbraco’s community site does describe necessary steps needed to enable external login providers. They eaven provide a tutorial on how to enable Google Authentication in Umbraco.

There is a  2 year old (from 2015) NuGet package available named UmbracoCms.IdentityExtensions.AzureActiveDirectory. It basically generates some C# files in you project – helping you configuring Umbraco to use Azure AD authentication. (source code on github).  by configuring OWIN.

The problem was that I could not get it to work out of the box. I really do not know why – but browsing Azures AD documentation and tutorials – I discovered the generated C# files added to my project were missing some settings.

We are not going to use the above mentioned NuGetPackage.

Install NuGet Packages

We need to install two NuGet Packages to enable OpenId to your project:

Using version 3.1.0 of all of the above keeps you safe 🙂

Allot of dependencies will be installed, so be warned. Here is a I got when installing UmbracoCms.IdentityExtensions on Umbraco Cloud 7.10.4:

Open Web Interface for .NET

Umbraco embraces Open Web Interface for .NET (OWIN) being the standard method of handling authentication in ASP.NET.  To get started you’ll need to create an App Registration using the Azure Portal.  If you are unfamiliar to the process there is exellent guide here.

When the app has been registered, you will need to write down and understand a couple of values:

ClientId / ApplicationId

The ClientId (ApplicationId on the Azure Portal) uniquely identifies the app towards Azure AD.


Azure Active Directory Instance is always: “” and identifies “public Azure” – this value might be something else if you are on a private cloud, but I have never seen such a private cloud in action.

Tenant ID

Tennant id is a Guid value uniquely identifying your Azure tenant.

Adding code

The App Settings section in Umbraco’s web.config should include the above mentioned values from Azure’s App Registration:

<add key="ida:ClientId" value="" />
<add key="ida:AADInstance" value="" />
<add key="ida:TenantId" value="" />
<add key="ida:PostLoginUrl" value="https://localhost/umbraco" />

Also add a class named UmbracoAzureActiveDirectoryExtensions to serve as extension method for the IAppBuilder we later will call during startup. Continue reading “Configure Umbraco to use Azure AD for Back Office user authentication”

Automate Business Processes using Azure Active Directory and Office 365

“How Office 365 and Azure Active Directory is imperative to creating value by harvesting multiple best of breed products and combining them to create one seamless solution”

Authentication Experience

Authentication is the process of making sure that a user is who he says he is. Most applications need to identify its users – and as tradition dictates in the Realm of Microsoft – Active Directory has the job of verifying the identity of users.

The current Cloud First world Azure Active Directory supports authentication flows such as OAuth2, OData and OpenIdConnect which are open standards embraced by Microsoft and should as well  be embraced by you.

If you are a corporation using Office 365 and/or Azure, you already have Azure Active Directory which is a standard platform when it comes to Authentication and Authorization. The philosophy is that developers should focus on building software and adding value, letting Azure Active Directory handle authentication and thus provide users with the best possible experience.

I often hear clients complain about their need to “go to different apps or sites” to get their job done. In my experience, if clients experience a transparent single sign-on integrated solution they will not feel that they are “visiting a different app or site”.

Example of what Integration and Authentication will be perceived

Take for example an Outlook and SharePoint Online user who daily needs to convert mail attached word documents to PDF files and store them on a special list in SharePoint Online.

Scenario 1 – Office 365 out of the box.

The process is supported in Office 365 “out of the box” – by saving or opening the attachment in Microsoft Word, save the document as a PDF document, and then upload the document to the SharePoint list of choice. The user experience is not optimal if this is needed to be done multiple times during a workday, because the user feels he needs to use 3 different apps to get the job done.

1. Microsoft Outlook to receive the mail

2. Microsoft  Word to convert the attachment to PDF and

3. SharePoint Online to upload the PDF document.

Scenario 2 – Outlook Web App

The process can be automated by having a developer create an Outlook Web App plugin that automates the conversion of the Microsoft Word document to PDF and uploading the PDF to the SharePoint Online list.  Here is how it could look like:

1. Use Microsoft Outlook to receive the mail

2. Use a custom build Outlook Button to make the conversion of the document and store the document in the SharePoint list – without ever leaving Outlook.

In this scenario the user only needs to press one button within Outlook to get the task done – clearly a more fluent work process.

What it takes to implement Scenario 2

The developer needs to know the Microsoft Outlook API’s and the Outlook plug-in architecture as well as how to use code to convert the Word document to PDF and how to use the SharePoint API’s to upload the document *

The code needs to be hosted – recommending Azure Web App for this, access (authorization) to Outlook and SharePoint needs to be granted and single sign-on needs to be in place so that the user does not need to sign-in while security in Outlook and SharePoint is respected. For this we could use Azure Active Directory’s App registration in Azure.

The process requires developers to have knowledge regarding:

1. Outlook Web Apps architecture, being extension points, API and governance.

2. Azure Web/API App’s and Azure in general

3. Active Directory App Registrations

4. Conversion of Word to PDF using programming

5. SharePoint Online API to upload the document to SharePoint

6. Knowledge of how OAuth2, OpenConnectId and Azure AD play together with Outlook, Azure Web Apps and SharePoint Online.

The result is a streamlined process where the user feels that he  can perform his task by pressing one single button – but in reality the process combines the power of Outlook, Azure, Azure Active Directory and SharePoint Online to automate the business process.

More complex scenarios

The above mentioned scenarios are often a bit more complex in real life. In addition to SharePoint and Outlook one might need to plug in other components that do not out of the box have Azure AD to handle the authentication. In that case developers should evaluate 3. party components and make sure that Authentication can be setup to use Azure Active Directory for Authentication.

In my next blog post I will investigate how Umbraco CMS might be configured to use Azure Active Directory to authenticate users – and thus can be configured to become a seamless component in a business process as SharePoint Online and Outlook are in the scenarios used in this post. Stay tuned.

* Instead of using outlook and SharePoint’s API’s, you can use Microsoft Graph‘s API to access Office 365 applications in a unified REST way.