Azure AD authentication in Kentico

Azure Active Directory (AD) authentication in Kentico project implements an Azure AD identity provider for Kentico 10, 11 and 12 to verify user accounts existing in a business directory and issue security tokens upon successful authentication of those users.

The following diagram demonstrates the login process flow

Prior to start integrating make sure that a Kentico application planning to outsource an authentication to Azure AD is registered in Azure AD first. Azure AD registers and uniquely identifies an application in its directory. This solution supports the definition of registration parameters in Kentico Settings at a website / global level, the key configuration fields are

• Client Id
• Application Key
• Tenant Id
• Azure Groups to sync

The below screnshots will guide you where to find the required Azure AD settings:

It is also important to enable access for your application as follows:

The module comes with two user controls for Login and Logout functionality, and a proxy script (/pages/AzureAuthRedirect.aspx) implementing the integration routine. So, that you can adapt the user interface for your needs easily.

Another thing to check in Settings is that you have specified a login page for users in front-end, go to "Settings -> Security & Membership -> Content" and set a "Website logon page URL" field to your login page with the placed Login control on it.

How to secure a page on your Kentico website?

1. Select a page you wish to put behind the login
2. Go to Page Properties -> Security tab
3. Select the required user roles to restrict access to the page in "Users and Roles" field under Permissions section
4. Specify access rights in "Access rights" table
5. Set a "Requires authentication" to "Yes" under Access section

Installation steps

1. Import a relevant Kentico module package for your CMS version:
   1. Kentico 10: Kentico10\AzureADAuthenticationModule_K10.zip
   2. Kentico 11: Kentico11\AzureADAuthenticationModule_K11.zip
   3. Kentico 12: Kentico12\AzureADAuthenticationModule_K12.zip

Go to Sites > Import site or objects > Upload and select a package. Tick off an "Import code files" checkbox during import.

2. Include the imported code files into your project in Visual Studio:

   1. CMSGlobalFiles\AzureADAuthentication\AzureADAuthenticationHandler.cs
   2. CMSModules\AzureADAuthentication\AzureADAuthenticationModule.cs
   3. CMSModules\AzureADAuthentication\AzureADAuthenticationSettings.cs
   4. CMSWebParts\AzureADAuthentication\Login.ascx
   5. CMSWebParts\AzureADAuthentication\Login.ascx.cs
   6. CMSWebParts\AzureADAuthentication\Login.ascx.designer.cs
   7. CMSWebParts\AzureADAuthentication\Logout.ascx
   8. CMSWebParts\AzureADAuthentication\Logout.ascx.cs
   9. CMSWebParts\AzureADAuthentication\Logout.ascx.designer.cs

3. Install the following Nuget packages into your solution:

   1. Install-Package Microsoft.Azure.ActiveDirectory.GraphClient
   2. Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory

4. Register the following handler in web.config:

   <add name ="AzureADAuthenticationHandler" verb="*" path="AzureADAuthentication.axd" type="AzureADAuthentication.Handlers.AzureADAuthenticationHandler" />

5. Rebuild your solution and open Kentico CMS Admin area

6. Fill in the following settings in Settings > Security & Membership > Authentication > Azure AD:

   1. Client ID
   2. Tenant ID
   3. Application Key
   4. Authentication Redirect Page

7. Make sure that your Kentico application is registered in Azure AD; note that the redirect URL has to be the full URL including the protocol and port, for example, http://localhost/AzureADAuthentication.axd or http://localhost/Kentico11/AzureADAuthentication.axd

   The below is an Azure admin interface where you can register your redirect URLs

8. Add an "Azure AD Login" webpart to a page you want to secure and then try to browse it in front-end and login!

Test Data

General application settings

For testing purpose you can use the following test details:

1. Client ID: f25b409a-888a-47bc-94cf-c1d27ac9ad57
2. Tenant ID: 20235006-a5ce-40f9-a061-cd97b588de50
3. Application Key: q7mX1-q[+LetIB42cAY.nsp8e4q[K452

Registered redirect URLs

The following Redirect URLs are registered:

1. http://localhost/AzureADAuthentication.axd
2. http://localhost/Kentico12_2/AzureADAuthentication.axd
3. http://localhost/Kentico10/AzureADAuthentication.axd
4. http://localhost/Kentico11/AzureADAuthentication.axd

Test user

Username: test@testdancinggoat.onmicrosoft.com Group: Test Group Password: Sxqp5t*9GD7E

Configuration Guide

1. Make sure that your Kentico application is registered in Azure AD;
2. Include AzureADAuthInKentico project into your Kentico solution;
3. Restore Nuget packages for AzureADAuthInKentico project;
4. Check Kentico references in AzureADAuthInKentico project (the ones pointing to /lib/ folder) and make sure that you use your Kentico assemblies;
5. Define Azure AD registration parameters in Kentico Settings at a website / global level: Client Id, Application Key, Tenant Id, Azure Groups to sync (see above about where to find them);
6. Build and run;
7. Now you are ready to secure your Kentico pages and use Azure AD accounts to access them:
   • Specify a login page for users in front-end, go to "Settings -> Security & Membership -> Content" and set a "Website logon page URL" field to your login page with the placed Login control on it;
   • Secure a page you want to be behind login (see the "How to secure a page on your Kentico website?" section above).

That is all, enjoy!

Contribution

Hope you found the above solution helpful, your contributions and suggestions will be very much appreciated. Please submit a pull request with your code enhancements.

License

The Azure AD authentication in Kentico module is released under the MIT license what means that you can modify and use it how you want even for commercial use. Please give it a star if you like it and your experience was positive.