Using ADFS with Azure for Single Sign-On in ASP.NET MVC

Active Directory Federations Services (ADFS) is an enterprise-level identity and access management service provided by Microsoft. ADFS runs as a separate service and hence any application that supports WF-Federation and Security Assertion Markup Language (SAML), can leverage this federation authentication service.

In this article, we are going to use ADFS configured in Azure VM for Single Sign-on implementation. If you have never configured an ADFS in Azure VM or need to know the benefits of using an ADFS, along with some key terminologies, I strongly recommend you to read this article first. The steps shown in this article are also applicable to ADFS which already exists on-premises. For demonstration purposes, we are not using on-premises ADFS but are going to use Azure VM to act as our domain controller and ADFS server.

This article is published from the DNC Magazine for .NET Developers and Architects. Download this magazine from here [PDF] or Subscribe to this magazine for FREE and download all previous and current editions

Applicable Technology Stack

1. Windows Server 2012 R2 DataCenter

2. Azure VM based ADFS OR on-premise ADFS

3. Self-Signed SSL Certificates

4. Visual Studio 2013 Community Edition

Important ADFS configurations

In this section, I will demonstrate what ADFS should consist of, in order to integrate well with your ASP.NET MVC application. I will be using the same setup as demonstrated over here.

Add details for existing AD user and create new user

The MVC application we are developing is a claims-aware application, therefore ADFS should send in the claims that will represent information of the user on a successful authentication. To make this possible, important details of each ADFS user must be configured in Active Directory. This section highlights settings which are necessary for a user to enable him/her for use of claims-aware application.

Login to the Active Directory server. In my case, it is the Azure VM. In your case it may be Azure VM or on-premises AD server. Remember the steps are going to be same irrespective of Azure VM or on-premises Server. For this article, we will use Azure VM.

From “Server Manager” options > select “Tools” menu > and open “Active Directory Users and Computers” option.

From “AntarikshDomain.com”, locate the user “antarikshadmin”.

Double click on the user to open the details window. Fill in the details in the “General” tab as shown in the following screenshot.

Now we will add another user in the same active directory. Right click on “Users” in the left hand panel and select option as “New User”.

I am going to add my name ‘kunal’ as a new user. If you wish, you can add yours or anybody else’s. Refer to the following screenshot for details. Click Next and provide a password of your choice. Make sure that you check the options “User cannot change password” and “Password Never Expires”. Click Next to continue and then click on Finish to complete the new user creation procedure.

What is my Metadata URL and where to find it?

First let me show how you can locate the metadata URL of your ADFS and in the next section, we will explore the why part of it.

To get your metadata url, open Server Manager or Azure AD VM (or on-premises AD machine) > and from “Tools” option > select “ADFS Management” option as shown here -

This step will bring up the “ADFS Management” window. Then expand the “Service” tab in the left hand panel and select “Endpoint” option. All endpoints available on ADFS will be displayed. Scroll to the bottom and you can locate the metadata URL as shown here –

If you observe, the metadata URL in the screenshot is being displayed as /FederationMetadata/2007-06/FederationMetadata.xml. This is only a part of the metadata URL. The full metadata URL would be your DNS name + the URL we just saw. As you know, in our case we are using Azure VM for hosting ADFS, therefore our Azure Cloud Service URL is nothing but our DNS name. Therefore in this case, the complete Metadata URL will be –

https://antariksh.cloudapp.net/FederationMetadata/2007-06/FederationMetadata.xml

If you have used the link I shared earlier to set up ADFS in Azure VM and followed all the steps till now, then the URL will work for you as it is. Now if you put this URL in a browser like IE, then this is what you will see –

It is absolutely fine if you are not able to make any sense out of this metadata. When we configure this metadata in our application, that’s when we will realize its importance.

Note – If you face any certificate errors like “There is problem with this websites security certificate” then there’s nothing to worry here. Just click on “Continue to this website (not recommended).” Option to continue. The reason this error gets displayed in the browser is because we are using Self-Signed Certificates.

If you have provided a different name to your cloud service, then your URL will be

https://YourCloudServiceName.cloudapp.net/FederationMetadata/2007-06/FederationMetadata.xml

If you are using on-premises ADFS, then you metadata URL will be –

https://YouDomainName.com/FederationMetadata/2007-06/FederationMetadata.xml

Before moving ahead, let’s first understand why do we need this Metadata URL and what is its purpose. This is explained in the next section ‘General Steps for Claim Based Authentication’.

General Steps for Claim Based Authentication

When we say that our application will use ADFS for authentication, it means that our application should be able to understand claims sent by ADFS. There are 4 generic steps involved –

Step 1 - Add logic to your application for supporting claims

When you are planning to build a claim-based application, your application needs to know how to validate security token coming from a security token service (in our case ADFS) and how to retrieve claim from that security token. Microsoft has provided rich classes in its Windows Identity Foundation (WIF) framework to handle implementation of claims-based application. The WIF framework provides a basic programming model for claim-based authentication. In order to use WIF, you will need to add a reference to the WIF assembly (Microsoft.IdentityModel.dll) in your WCF or ASP.NET application.

Step 2 - Acquire or build an issuer (ADFS)

I have already implemented this step over here Configuring ADFS in Azure Virtual Machine. Needless to mention, the same steps can be used if you are using on-premises ADFS.

ADFS will be issuing security tokens and claims, therefore ADFS is also termed as Issuer. In a broader view, all Identity Providers are treated as Issuer or Secure token Services (STS).

Step 3 – Configure application to trust the issuer (ADFS)

Once you have developed a claim-based application using WIF and have used ADFS to issue security token, the next step is to set up a trust relationship. This is a very important step. An application needs to trust the ADFS to identify and authenticate users and make claims about their identities. When you configure an application to rely on a specific issuer, you are establishing a TRUST (or TRUST RELATIONSHIP) with that issuer. The application needs to understand what claims ADFS will be offering, what key application should be using to validate the tokens? What URL the user should be using to request token? And so on.

ADFS provides answers to the above questions using “federation metadata”. This is an XML document which ADFS provides to the application and in our case it can be obtained from the URL –

https://antariksh.cloudapp.net/FederationMetadata/2007-06/FederationMetadata.xml

I hope you now understand the important of the ADFS Metadata URL.

It includes a serialized copy of the issuer’s certificate that provides your application with the correct public key to verify incoming tokens. WIF includes a wizard that automatically configures application’s identity settings based on this metadata. We just need to give the wizard the URL for the ADFS, and it downloads the metadata and properly configures your application.

Step 4 – Configure the issuer (ADFS) to know about your application

The trust relationship is always two ways. In Step 3, we saw that by using Metadata URL, we can configure trust relationship between Applications and ADFS. Now ADFS needs to know a few things about an application before it can issue it any tokens. These questions include information related to URI of the application, which claims are required by applications out of issue by ADFS, URL of the application to receive tokens and so on.

ADFS can get this information about the application when we configure the application as Relying Party. Our application is going to rely on ADFS for security token and authentication therefore it is called as the Relying Party.

We will follow these 4 steps so as to implement ADFS integration in an ASP.NET MVC application.

Create ASP.NET MVC application secured by ADFS

So here we go with the actual implementation. I hope you have noted the technology stack I have mentioned at the beginning of the article.

Create claims-aware ASP.NET MVC application

The first step would to be open Visual Studio 2013 in the administrator mode and click on File > New > Project. A dialog box appears where in you put the name of your project as SingleADFSDemo (or anything else of your choice) and specify the appropriate location. When we click OK, another pop up appears where we need to choose the template of the project. We will select MVC template here. As soon as we select the MVC template, automatically in the right hand panel, the authentication mode changes to “Individual User Account” and we don’t want that!!

So click on “Change Authentication” button, another pop up appears where you can select the option as “Organization Account”. In the right hand panel, a drop down appears with default value selected as “Cloud-Single Organization” and we don’t want this option too!!

In the same drop down, select the option On-Premises and here is the catch/confusion! Let’s understand these drop-down options one by one!

• Cloud - Single Organization – this option should be chosen if your application is authenticating against Azure Active Directory.
• Cloud – Multiple Organization – this option is for SaaS applications where one application will be used by multiple clients.
• On – Premises – This option allows you to connect to any WS-Federation provider (like ADFS) which offers Metadata document and this is our option for the article!

Note – Don’t go by the literal name On-Premises. This option suggests that you can use any corporate ADFS irrespective of the fact that ADFS is hosted on-premises or on Azure VM.

So select “On-Premises” and the following screen appears asking for 2 types of information.

• On Premises Authority – this should be our ADFS metadata URL which can be from Azure VM based ADFS or On-premises hosted ADFS.
• App Id URI – This will be the URL assigned to the ASP.NET MVC project we are creating using IIS Express. If we host it on a custom domain like https://kunal.com then this URL of custom name will be my App Id URI. Of course this can be changed later after project creation using web.config. We are going to keep it blank and let it get auto-populated after project creation.

Add the metadata url (https://antariksh.cloudapp.net/FederationMetadata/2007-06/FederationMetadata.xml ) of domain Antariksh, keep App Id URL blank and click on OK to continue. Keep rest of the options as it is and click on OK to create the project.

After project creation, expand the references from Solution explorer and you will observe that System.IdentityModel.dll reference has got added automatically.

In web.config an entry for <system.identityModel> gets added with all the settings required for making application claim-aware and trust the metadata of ADFS. It is also important to note here that localhost IIS express URL will be added under <audienceUris> tag and metadata URL, realm etc. added under <appSettings>.

The audience URL is the application URL so at a later date after finishing testing with localhost, let us say we wish to host the MVC application on:

• Azure cloud service, then my audience URI and realm would be https://mycloudservicename.cloudapp.net/ or
• Azure webApps, then it would be https://mywebsites.azurewebsites.net/ or
• Custom domain like kunal.com, then it would be https://kunal.com/ and so on. You got the idea right?

So hereby we have defined the trust relation in our MVC application or Relying Party to Azure VM based ADFS.

Adding ASP.NET MVC app as Relying party trust in ADFS

Let us move back to ADFS to do some configurations. In this step, we will essentially tell ADFS that our MVC application with localhost url is a trusted application and you can send the security tokens to it after successful authentication from a user. In technical terminology, this is nothing but adding relying party trust in ADFS.

So login to the ADFS Azure VM. Open Server Manager > Tools > ADFS Management. Expand “Trust Relationships” from left hand panel and select “Relying Party trusts” option. You will see that Device Registration Service is already present as a relying party. Now click on the option “Add Relying Party Trust” in the right hand panel.

The Add relying party wizard will appear. Click on the Start button to continue. Select the option “Enter data about relying party manually” and click on Next to continue. Now we are going to use our localhost URL as relying party therefore we are providing the name as localhost application.

Click Next to continue. In the Choose Profile window, select “ADFS Profile” option and click Next to continue. The ADFS configured on Windows Server 2012 is ADFS 3.0 therefore we are not selecting 1.0 and 1.1 profile option.

In the “Configure Certificate” option let’s not do anything. This window gives you an option to choose the certificate for encrypting tokens. As of now, we are encrypting none of the tokens therefore simply click on Next to continue. In the “Configure URL” window, select the checkbox against the option “Enable support for the WS-Federation passive protocol”. The Textbox will get enabled and this is where we need to put our relying party URL or in simple words- our MVC application URL. From web.config file, copy value for the key ida:AudienceUri and put in the textbox as shown here and then click Next to continue.

In “Configure Identifiers” we already have the required relying party added, therefore simply click Next to continue. Now select “I do not want to configure multi-factor authentication settings for this relying party trust at this time” and click Next to continue. Select “Permit all users to access this relying party” and click Next to continue.

In the “Ready to add trust” window, click Next to continue. In the “Finish” window, select the checkbox to open the claims rules and click on Close.

The Edit claim rules window pops up. At this point, ADFS knows about our MVC application but there a couple of additional things required. This is where we tell ADFS which claims need to be sent to the relying party and what values will be present in those claims.

Click on the “Add Rule” button.

Select template value as “Send LDAP attributes as claims”. Actually claims will be sent by Active Directory and Active Directory is a LDAP based store, therefore we are selecting this template. Now click on Next to continue.

In configure Rule window, provide the name for the rule as Send AD Attributes. Select the attribute store as “Active Directory”. In the mapping table, map the values as shown here –

Click on Finish to exit the wizard and then click OK to complete claims rules configuration.

Running the application

Alright. Now is the time to test everything we have done so far. Going back to Visual Studio, hit F5 to start the application in debug mode. Click continue on certificate errors and hurraahh! If you are running your application in IE, you will see a credentials box from our Azure VM or on-premises ADFS as shown here –

Enter the credentials of antarikshadmin or your ADFS admin and you will be redirected to the home page of the MVC application with your admin name flashing in the right hand upper corner as shown here –

Isn’t this amazing? We did a complete ADFS integration in our MVC application without writing a single line of code! Let’s go further and analyze the claims we are receiving from ADFS.

Viewing the claims retrieved

Now we must understand the different claims our application is receiving. We are going to populate all the received claims in the About action. Let’s first rename the About action to Showclaims from Layout.cshtml as highlighted here –

Modify the HomeController About action to ShowClaims and add some code to return claims to the views. You will need to use System.Security.Claims reference at the top. Refer to the following screenshot for details –

Rename the About.cshtml view to ShowClaims.cshtml and add the following code in the view as shown here –

Run the application, enter ADFS admin credentials. After successful login, click ShowClaims action at the top and all the claims sent by ADFS will be displayed.

The way we used admin user, other AD users can also be used in the same way. Remember we configured an extra user in ADDC called ‘kunal’ or whatever you chose the username as. Go ahead and use the credentials of this new user created in ADDC and see if you get similar results.

Now you can use any of these claims like email in your application and can provide authorization to the user based on authorization roles and rules in your database.

Making life easier for developers to bypass ADFS authentication during development

One of the most frequent questions I have encountered in person and in forums is about developers asking how to bypass ADFS temporarily. Once ADFS integration is implemented in a project, every time you run the application, it keeps asking you to enter the credentials and Developers who are working everyday on the same project, are bound to get frustrated. That’s where I thought it is worth to spend some time explaining a simple technique to bypass ADFS authentication mechanism during development work.

Just open the web.config, search for <deny users="?" /> and comment it. You are done! Now if you run the application, ADFS login box will not appear and entire application will be accessed anonymously.

Conclusion

In this article we saw how easy it was to implement a single ADFS integration in ASP.NET MVC and how to retrieve the claims, relying party, claims rules and many other aspects involved with a typical WSFederation implementation using Windows Identity Foundation (WIF) technique.

We can also configure our ASP.NET MVC application to consume multiple ADFS authentication (either Azure VM configured or On-premises) using Microsoft OWIN KATANA. Keep an eye out for an upcoming article on multiple ADFS authentication on www.dotnetcurry.com

This article has been editorially reviewed by Suprotim Agarwal.

C# and .NET have been around for a very long time, but their constant growth means there’s always more to learn.

We at DotNetCurry are very excited to announce The Absolutely Awesome Book on C# and .NET. This is a 500 pages concise technical eBook available in PDF, ePub (iPad), and Mobi (Kindle).

Organized around concepts, this Book aims to provide a concise, yet solid foundation in C# and .NET, covering C# 6.0, C# 7.0 and .NET Core, with chapters on the latest .NET Core 3.0, .NET Standard and C# 8.0 (final release) too. Use these concepts to deepen your existing knowledge of C# and .NET, to have a solid grasp of the latest in C# and .NET OR to crack your next .NET Interview.

Click here to Explore the Table of Contents or Download Sample Chapters!

Author

Kunal Chandratre is a Microsoft Azure MVP. He is working as Azure SME in leading software company in (Pune) India. He also works as a Freelancer with various organizations for Azure support and provides quick start trainings on Azure to corporates and individuals on weekends. He regularly blogs about his Azure experience and is a very active member in various Microsoft Communities and also participates as a ‘Speaker’ in many events. You can follow him on Twitter at: @kunalchandratre or subscribe to his blog