Configuring multi-tenant authentication with Azure App Service authentication options

Using the Azure App Service authentication options you can easily secure your web applications and APIs no matter the technology used to build them. Did you know that the authentication options can be used to secure both single- and multi-tenant applications?

Security through configuration

When building web applications and APIs one of the key ingredients is securing them. Through security you can both control the access to the whole application and keep personal data private.

If you choose to host your web applications and APIs on Microsoft Azure, you can simplify the authentication process by using the App Service Authentication options. No matter what technology your application is built in, you can add an authentication layer to your application without modifying your code.

Azure App Service Authentication currently supports a number of identity providers amongst which Azure Active Directory (AAD), which is a great option if you want to build applications for business users and want to allow them to authenticate using their existing organizational account.

Securing Azure Web Apps and API Apps with Azure Active Directory

Using the App Service Authentication options you can easily secure your web application or API by completing the following steps:

  • in your Azure subscription create a new Azure Web App/API App
  • on the Settings blade, from the Features section click the Authentication / Authorization option
    The 'Authentication / Authorization' option highlighted on the Settings blade in Azure

  • on the Authentication / Authorization blade enable the App Service Authentication setting
    The 'App Service Authentication' toggle highlighted on the 'Authentication / Authorization' blade in Azure

  • in the list of Authentication Providers click Azure Active Directory
    The 'Azure Active Directory' provider highlighted in the list of available authentication providers in Azure

  • on the Azure Active Directory Settings blade choose either the Express or the Advanced configuration mode
    The 'Management mode' options highlighted on the 'Azure Active Directory Settings' blad in Azure

Despite the fact that you haven't built any authentication logic into your web application or API, if you deploy it to an Azure Web App or API App secured using the App Service Authentication options, you will be prompted to login using an organization account before you will be able to access it.

Azure Active Directory login page displayed when trying to access a web application hosted in an Azure Web App secured with the Azure App Service Authentication options

It's for a single tenant only

If you follow the configuration steps described in the Azure documentation, you will notice that authentication is tied to the Azure Active Directory where the AAD Application is registered. If you try to use an organizational account from a different tenant, like you would when building multi-tenant applications, you will get the following error:

AADSTS50020: User account [email protected]' from identity provider 'https://sts.windows.net/bb6ba7bc-01bd-4241-a30a-a8ec32ec6a1e/' does not exist in tenant 'Contoso' and cannot access the application '9e8652ce-eca7-416f-b87c-1eb0351df99d' in that tenant. The account needs to be added as an external user in the tenant first. Sign out and sign in again with a different Azure Active Directory user account.

Error when trying to authenticate with an organizational account from a tenant different than the one used to register the AAD Application

So does this mean that App Service Authentication options are only good for securing single-tenant web applications and APIs or is there a way to use them for securing multi-tenant applications as well?

Single-tenant vs. multi-tenant applications

When registering applications with Azure Active Directory you can choose whether the particular application is single-tenant or multi-tenant.

Multi-tenant option highlighted on the AAD Application configuration page

Single-tenant applications can be accessed only by users who have an organizational account in the same AAD where the application is registered. Multi-tenant applications can on the other hand be accessed by anyone who has a valid organizational account.

Imagine that you had an AAD called contoso.onmicrosoft.com. If you registered a single-tenant application in your AAD, only users with accounts such as [email protected] would be able to access that application. Users from other tenants, such as northwind.onmicrosoft.com, would be denied access to that single-tenant application. If that application was however configured as a multi-tenant application both users would be able to access it.

Configuring multi-tenant authentication with Azure App Service Authentication options

Using the Azure App Service Authentication options you can easily enable multi-tenant authentication for your application. To do that:

  • ensure that your AAD Application is configured as multi-tenant
    Multi-tenant option highlighted on the AAD Application configuration page

  • in the App Service Authentication options, configure Azure Active Directory authentication using the Advanced mode
    Advanced configuration mode enabled for Azure Active Directory authentication in the Azure App Service

  • in the Client ID field specify the ID of the AAD Application used to secure your web application or API
  • leave the Issuer Url field empty
    Advanced configuration options for multi-tenant authentication with Azure Active Directory

Most of the manuals and articles, that describe the process of configuring web application authentication using the App Service Authentication options, say that in the Issuer Url field you should specify the ID of the AAD from which users should be allowed to authenticate in your application. The consequence is, that users from other AADs are denied the access. What however isn't clear, that if you want to build a multi-tenant application and allow users from different organizations sign in to your application using their existing account, you should leave this field empty.

If you would try to authenticate to your web application using an account from another organization now, you will very likely get the following error:

An error of type 'access_denied' occurred during the login process: 'AADSTS65005: Resource '15385d16-36c5-4584-b96d-88a12f85fdde' does not exist or one of its queried reference-property objects are not present. Trace ID: 647cfb1d-b979-4e3e-8be3-8816ba9f811e
Correlation ID: 085a007a-6b28-4114-920d-db4c21a7a30c
Timestamp: 2016-03-11 15:18:34Z'

Authentication error when trying to login to a multi-tenant web application secured using App Service Authentication options

This is caused by the fact that the first time you try to authenticate to a multi-tenant application it isn't registered with your organization's AAD. To fix this issue you have to trigger the consent flow which will allow the user to login with their organizational account and grant the application the necessary permissions. The consent flow can be triggered by adding &prompt=consent to the Azure login URL. This is something that you would typically do on a sign-up page promoting your application.

When you start the consent flow, at first you will see the regular Azure login page, but after you authenticate, you will be prompted to grant the web application the necessary permissions:

Granting permissions to a multi-tenant web application

After you grant the application the necessary permissions you will be able to access the application:

User from another organization successfully authenticated in a web application secured with App Service Authentication options

Having completed the consent flow the application has been registered in your AAD and from now on you can access it by directly logging in to it.

Summary

Using the Azure App Service authentication options you can easily secure your web applications and APIs no matter the technology used to build them. By leaving the Issuer Url field in the Azure Active Directory settings empty and completing the consent flow you can enable multi-tenant authentication for your web application or API without any additional code.

Comments

comments powered by Disqus