Using Active Directory and AzureAD in SSO

A very common scenario for authentication is that an organization has an existing on-premise Active Directory that it wants to use to get a single sign-on experience for applications hosted in the cloud.

Using Active Directory and AzureAD in SSO

A very common scenario for authentication is that an organization has an existing on-premise Active Directory that it wants to use to get a single sign-on experience for applications hosted in the cloud.

AzureAD-Connect

What are the options

There are actually an number of ways that this scenario can be accomplished:

  1. Using AzureAD Connect to extend the on-premise AD to the cloud
  2. Using an AD FS proxy exposed on premise
  3. Using 3rd party solutions like Auth0 and others to facilitate SSO

In this post I'll be describing the 1st of these as this is by far the easiest and cheapest if all you need is Active Directory authentication. Note that when you want to mix AD with social logins, the choice may not be as straight forward. Although there is an AzureAD B2C offering with these capabilities, there is an associated cost that will have to be compared to other offerings.

Describing the solution

Many organizations already have Office365 or are considering moving some or all of their mail and document storage into the cloud. Office365 already offers SSO to its users based on AzureAD and AzureAD Connect. So basically we're just using what is already there for our own applications.
Even if the organization does not have an Office365 account and has no plans in that direction, we can still use this infrastructure that is provided for free!

If you are not familiar with all the moving parts of this solution, you will have some reading to do. I will include links to relevant documentation in the post.

The solution will involve:

  1. Creating an Azure subscription
  2. Setting up Azure AD to use a custom domain
  3. Preparing the on-premise Active Directory
  4. Installing and configuring AD Connect
  5. Registering the application in Azure AD
  6. Adding authentication to the application

Multi-tenant applications

If your application will allow users from multiple organizations to log on with their own AD username and password, you will have to ensure that each organization that you want to enable has its own AzureAD instance configured, either using an Office365 tenant, or as described below. The application will now be described as a multi-tenant application in Azure AD. You will still only have to register the application once, in your own Azure AD instance, but you have to enable the multi-tenant option when registering it.

Creating an Azure subscription

The easiest way to get started with Azure is to go for the free trial offer. Note that this is only available once per organization. If you already have an Azure subscription, than you will already have an AzureAD instance as well. Once the trial ends you will have to start paying for the resources you consume, but the actual Azure subscription and the Azure AD instance associated with it remain free, as long as you do not exceed the limits of the free tier.

Setting up Azure AD to use a custom domain

Did I just say for free earlier? Yes, there is a large free tier to AzureAD, allowing up to 500k objects. There are some downsides to the free offering as well, like the lack of an SLA. You must consider whether that is important in you scenario and maybe choose the Basic or Premium tier instead. Having no SLA does not mean having a bad service, just that you will not be first in line for the helpdesk staff and you are not eligible for compensation when there is an outage. Multi-factor authentication is also a paid option that may be well worth investing in.

If you are happy with what the AzureAD free tier has to offer, then you are good to move on to the next step: setting up a free Azure subscription.

The way AzureAD works is a bit complicated to explain. An AzureAD instance does not live within an Azure subscription like other resources, but you need a subscription to get access to it. In fact an AzureAD instance can be linked to multiple Azure subscriptions at the same time. This helps you to organize and manage resources in a way that makes sense for your organization or, in a multi-tenant scenario, to keep resources of different customers separated.

The best practice advise from Microsoft is that any organization should only have an single AzureAD instance associated with it for internal use. Rights to subscriptions and resources can be delegated from that instance as needed, so there is no need to have more than one. Personally I think that there are cases where a second AzureAD is warranted to separate off security for high risk resources, but mostly you would want the easiest possible setup to help with management of all your resources.

Great, now the AzureAD is in place, it needs to be configured to receive the users from the on-premise AD. By default the AzureAD will have a domain name like mycompany.onmicrosoft.com, which is not very user friendly. So the first thing to do is to set up and verify a custom domain name on your AzureAD instance. This involves adding a TXT-record to your public DNS, so if you do not manage that yourself, you may have to request some assistance from your DNS provider. Most providers provide a DIY portal so you can manage this yourself. Note that if you have not already, you need to set up your on-premise AD to use this domain name as an alternate UPN suffix.

Preparing the on-premise AD

First of all you need to choose the server that will be the host for AD Connect. Typically this will be one of the domain controllers, although this is not strictly required. Note that Windows Server Essentials has its own integration with Azure AD and does not require or support AD Connect.

There are some prerequisites to installing and configuring AD Connect. The full list can be found here. Don't be put off by this, because in 90% of cases there are only a couple of really important ones. If you are already running AD on Windows 2012 of later, you will have very little to do. Mainly you need .NET Framework 4.5.1 or later, Powershell 3.0 or later and the MSOnline PowerShell 1.0 module. Note that the tools currently support on version 1.0 of the module only.

Installing Azure AD Connect

In almost all cases you will be best off using the Express installation of AD Connect. Unless you know what you are doing, I would discourage you from doing a custom install yourself.

The Express install wil automatically enable password synchronization between your on-premise Active Directory and your Azure AD instance, by which password hashes will be stored both in the cloud and on-premise. If this is not something you want to happen, you will have to opt for the custom install. The options then will include pass-through authentication, so that hashes are only stored on-premise. The compromise is that every authentication call will involve a round-trip to the on-premise AD Connect server, making it slower and not as reliable.

The installation wizard is really simple and only has 5 steps. If you want to filter which accounts get synchronized, you should uncheck the Start the synchronization process as soon as configuration completes box on the last page. That way nothing will get synchronized until you have finished your configuration. After that you can manually enable the synchronization scheduler.

Registering the application in Azure AD

Now the application will have to be registered in the brand new Azure AD instance we just created. This is actually quite easy through the Application Registration Portal of Azure AD. Just login with a user that is associated with the right Azure AD tenant and register your application. Depending on the type of application you are registering, you can pick and follow a guide from the bottom of this page. This procedure will register the application for the v2 endpoints which basically means that is will be compatible with OpenId Connect and Microsoft Graph. Some older Office 365 features may require v1 endpoint authentication, but its unlikely you will need those. Other limitations can be found here.

If your application will need to interact with Azure AD (to read user profiles, to query groups or even to update information) or the Microsoft Graph you can add the required scopes to your application registration. If you do, when users log in to your application they will be prompted to give their consent for these rights to be given to it. The requested scopes will end up in the access token given out to the application so it can access the respective resources.

For multi-tenant applications this will only be done once in the Azure AD of the organization that is publishing the application. when multi-tenancy is enabled, the application will be registered automatically in the other Azure AD tenants when a user tries to log in to it for the first time. The administrators of each Azure AD tenant will be able to restrict usage of the application by their users if they should wish to do so.

In the free and basic tiers of Azure AD there is a limit on the number of applications each user can have for SSO access to. Currently the limit is 10 apps per user, with Office365 also counting as one. You can get around this limit by registering another authentication provider (like Auth0, Google Identity or IdentityServer4) instead of your actual application. These can do their own registration of applications and will only count as one towards the Azure AD limit, however they may come with their own costs.

I would not encourage you to share the Client ID of your application registration between applications to get around the limit, because you will loose control of access to individual applications. The exception here is if you have multiple clients (for instance native mobile and web) that can be considered as being a single application, so access control can be safely shared. If at any time you need to reset one of the client secrets, maybe because it has been leaked, you will need to update each client that uses it. Another reason sharing them is not the best idea.

Adding authentication to the application

The instructions to add authentication to the application after registering it with Azure AD can also be followed in the guides I mentioned earlier. However I myself prefer to rely on the OpenID Connect compatibility of the v2 endpoints. Whatever the kind of application you are building and whichever language you are using to build it, there will probably be a certified client library for it. Even if there is not, there usually is some kind of basic OAuth2 (OpenID Connect is a superset of the OAuth2 specifications) library that you can use and extend. Do not under any circumstances try to build this yourself unless you know exactly what you are doing.

I will not go into detail here on the different OAuth flows you should (and should not) use for each authentication scenario, that will be for some future post, but you can find the supported scenarios in the documentation.

The endpoints you should configure in the library to authenticate against are as follows:

For Use
interactive authentication
(like the implicit grant)
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
non-interactive authentication
(like using a refresh token)
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token

The {tenant} token in these urls has a special meaning. Usually it will be a guid, in fact the Directory ID of your Azure AD instance. You can find the id on the properties page of your Azure AD instance in the Azure Portal. For a multi-tenant application however that would be no good; only users of one specific Azure AD instance would be able to log in. For these scenarios there are 3 specific values for the {tenant} token:

Value Description
common Allows users with both personal Microsoft accounts and work/school accounts
organizations Allows only users with work/school accounts
consumers Allows only users with personal Microsoft accounts

If you choose one of these options, Azure AD no longer cares to which Azure AD instance, if any, a user belongs and will grant access automatically. It will be up to you to verify the organization the user belongs to is allowed to log in using the tid claim in their id token or access token.

Conclusion

Setting up SSO authentication is inherently complicated. Using an on-premise Active Directory as a credential store for applications has however become a lot less difficult with the introduction of AD Connect. Also writing multi-tenant applications with SSO support has been made really easy with the work Microsoft has done on Azure AD. Having used AD FS previously in such a multi-tenant federated SSO setup, I can tell you that there was a whole lot of frustration involved that I am not going to miss.

While Azure AD may not be the best solution for every scenario, it does offer a very complete set of features and is pretty easy to use and configure if you are mainly developing applications that stay in-house.

For organizations that are taking their first steps into using developing SaaS applications we have found that being able to offer SSO with AD to customers early on can make the difference when it comes to closing deals. Customers of any size have become accustomed to having an SSO option on every application and are willing to pay a premium for it, although as I have hopefully shown here it does not take much to make it happen.

Related Article