Claim-Based Authentication using Microsoft Azure AD with Kentico
This article is a step-by-step tutorial on how you can set up Azure AD authentication with Kentico. We will be using Claim-Based authentication for this purpose, and Azure AD will be acting as an authentication provider.
Before you start, make sure that you have an existing Azure subscription. If you don’t have a subscription, you can get a free trial.
The provided concept is only responsible for authentication. We won’t be getting into roles and how to sync Azure AD with the Kentico instance. This will only be mentioned at the end of this article with a link to our documentation.
In our demo, we are running Kentico locally on this URL: http://localhost/Kentico82. You can use any URL hosted locally or running from the server.
Step 1 – Create Your Active Directory in Azure
Firstly, we need to create the AD in our Azure subscription. For this demo, we won’t be syncing with the existing one as this is out of the scope of this tutorial. There are plenty of related solutions that can be found on the internet.
So let’s start:
Click New > Active Directory > Directory > Custom Create
The only properties you are required to fill in are the name of the AD. This can be anything you like to use to identify your instance. The domain name under your AD is represented as well as the location.
Note: You can use your own domain with AD. However, this is again out of the scope of this tutorial
Step 2 – Create Your Test User
As we created a blank Active Directory, we will need to add some users so we can actually test it. For our demo, we will create just single a User test@[our AD domain].onmicrosoft.com
Then we need to insert basic user details (First Name, Last Name, and Display Name), and we keep the role as a predefined ‘User’.
The last step is to generate a temporary password.
Note: Write down this password, because we will use this later when we test our authentication
Step 3 - Create Azure Access Control Services (ACS)
ACS is an Azure service that provides an easy way for you to authenticate users to access your web applications and services without having to add complex authentication logic to your code.
The ACS is the Claim-based identity provider that actually sits between Azure AD and Kentico, and makes this process much simpler.
Step 4 - Create Application Endpoint
At this stage, there are no connections between ACS and Azure AD. To set this up, you need to create an Application Endpoint, which will be used by our ACS.
You only need to name it and select the web application type
Now you need to set up the connection via specifying SIGN-ON URL and APP ID URI. This URL is from the ACS created in Step 3.
Note: Make sure that your link starts with https
Step 5 – Copy Application Federation Endpoint for ACS
After you create the application in Azure, you need to get the endpoint URL, simply by clicking “view endpoints”. There you need to copy the ‘Federation Metadata Endpoint’ to the clipboard. This value will be used in ACS.
Step 6 - Now You Are Ready to Setup Your ACS
Navigate to your ACS namespace in the Azure portal and click “manage”.
Step 7 – Add Your Application as an Identity Provider in ACS
At this step, we create the Identity Provider for our Azure AD. Please follow the settings from the screenshots below. The most important thing is to paste the Federation Metadata Endpoint URL from step 5.
Select WS-Federation identity provider
Give your provider name and paste your WS-Federation Metadata Endpoint URL from step 5.
Step 8 – Add Your Application Details to the ACS
As mentioned at the beginning of our demo, the Kentico site is running locally on http://localhost/Kentico82. We need to allow our application to be able to use the Identity Provider. For this purpose, we have to add our Kentico site as a Relying Party Application in ACS
You need to specify at this screen;
Name – Any identifier for your reference
Realm – This is a URL where your Kentico application runs. (In our demo it is localhost)
Return URL – Expected URL where the ACS redirects with the security token
Identity Providers – tick the Identity Provider we created in the previous step (we named our Identity Provider as ‘Kentico AD1’)
Step 9 – Generate Your Claims
Once you’ve connected your application with the ACS, you need to have some claims that will be passed to our site during the authentication process. For our demo, we will only generate default claims, which are sufficient for the authentication. You may remove some of the claims as they are not used by Kentico anyway.
Generate default claims.
Step 10 – Setup Kentico to Use Claim-Based Authentication
More details on the Claim-based setup can be found in our documentation.
Enable WIF authentication needs to be checked
Identity Provider URL – this is your ACS-hosted login page. This URL will look similar to this one > https://kenticoad1.accesscontrol.windows.net/v2/wsfederation
Security realm – This is your application identifier. This has to be the same value as in the Realm settings in ACS
Trusted certificate thumbprint – This is a value from ACS. It can be found under Certificates and keys > Your X.509 Certificate > There is a Thumbprint value under Certificate
Step 11 – Test Your Authentication
If you’ve done everything correctly, you can now navigate to http://localhost/Kentico82/Admin page. This will redirect you to the Microsoft login page.
Here you just need to add your test user’s login details. Do you remember your password from step 2?
Now you need to update the user password as the one we created was only temporary.
If everything works correctly, you should be redirected to the ‘Access denied’ Kentico page. This means that this user doesn’t have permission to access the Kentico Admin interface. However, the user was successfully logged in.
Note: Kentico created a new user in the system with the “Is External” flag. Our claim-based implementation handles only user authentication (uses only the name and email from the token). As a result, you need to take care of authorization in Kentico separately. This means that you have to have role mappings already in Kentico.
More info here.
Step 12 – Check Successful Login
Now we can verify that the user is successfully logged in. Navigate to the home page and you will see the current user’s UserName.
This is all from this tutorial. We can see that setting up an Azure AD as an Identity Provider with Kentico is not very complicated. You only need to understand the process and then it is pretty straightforward.
Next Steps to Synchronize Azure AD with Kentico
To sync Azure users and roles you can use our AD import utility. More info can be found in our documentation.