Creating an ASP.NET Relying Party application for ADFS 2016

In my Pluralsight course “Implementing Windows Server 2016 Identity Federation and Access“, I use a sample application as a relying party that leverages ADFS for it’s authentication.  This post will describe how to create and configure that ASP.NET MVC application within Visual Studio, and configure the corresponding Relying Party Trust in ADFS 2016.  In a future post I will show how to deploy the application to an IIS server.

First, on your development computer running Visual Studio, make sure you can reach the XML metadata endpoint for the ADFS server on your network.  This could be a lab network of virtual machines, or your organization’s actual network.

The path to the ADFS XML metadata is always “your ADFS server FQDN”, followed by a path to the FederationMetadata XML document, which for ADFS 2016 is “/FederationMetadata/2007-06/FederationMetadata.xml”

e.g. https://youradfsservername/FederationMetadata/2007-06/FederationMetadata.xml

If you can reach the ADFS server in your browser, then you are ready to configure an ASP.NET application to use ADFS for authentication.

Open Visual Studio, and select “File -> New Project”.

In the dialog that opens, select the “ASP.NET Web Application (.NET Framework)” template, under the Web node.

Name the project “ClaimsApp” (or whatever you choose).

Click OK.  On the next page of the New Project wizard, select “MVC” for the project type, and click the button labeled “Change Authentication”.

In the dialog that opens, choose the radio button: “Work or School Accounts” on the left.  Then select “On-Premises” from the drop-down list.  This enables the text box to add the endpoint to your ADFS FederationMetadata XML document – the same one you opened in your browser earlier.  Enter the URL to FederationMetadata.xml in the “On-Premises Authority” text box.

In the “App ID URI” text box, enter a unique identifier for your application in the form of a URI.  Note that this does not need to be the actual URL to your relying party application, this is just a unique identifier that gets passed in the URL to ADFS, so that ADFS will know which relying party application is calling.

Click “OK” and “OK” again to create the new ASP.NET Web Application.

When the application is created, open Solution Explorer and look at the web.config file.  Notice under <appSettings>, the key “ida:ADFSMetadata” contains the URL to the FederationMetadata.xml file, and “ida:Wtrealm” contains the unique identifier you entered.  Make note of this unique identifier, as you will need it when configuring the relying party in ADFS.

Now open Solution Explorer again, and double click on “Index.cshtml”, under the Views->Home folder.

Remove all the text in the Index.cshtml file and replace with the following code:

@{
ViewBag.Title = "Home Page";
}

<div class=”jumbotron”>
<h1>Claims Display App</h1>
</div>

<div class=”row”>
@{
var claimsIdentity = User.Identity as System.Security.Claims.ClaimsIdentity;

if (claimsIdentity != null)
{

foreach (System.Security.Claims.Claim claim in claimsIdentity.Claims)
{
<div>
<div><b>Claim Type: </b>@claim.Type</div>
<div><b>Claim Value: </b>@claim.Value</div>
<div>——————————————-</div>
</div>
}
}
else
{
<b>Claims are null.</b>
}
}
</div>

This code will display all the claims that are returned from ADFS after authentication.

Next, in Solution Explorer, right click on the project name and in the menu that opens, click “Properties”.

Click the “Web” menu item on the left, and copy the “Project URL” at the bottom.  This will be the reply URL that ADFS will redirect to.

Now switch over to the VM that’s running ADFS, and open up ADFS Manager.  Expand the nodes under ADFS in the left tree menu, and right click on the “Relying Party Trusts” node.  In the menu that opens, click “Add Relying Party Trust”

In the Wizard that opens, select the “Claims Aware” radio button and click “Next”.

On the next page of the wizard, select “Enter data about the relying party manually” and click “Next”.

Give the Replying Party Trust a display name – note this is only used by ADFS, but will appear on error pages also.  Click “Next”.

Click “Next” on the “Configure Certificate” page.

On the “Configure URL” page of the wizard, select “Enable support for the WS-Federation Passive protocol”.  In the text box that gets enabled, paste in the home page URL of your relying party application that you copied from the properties page in Visual Studio.  Ensure there is a trailing forward slash “/” in the URL. Click Next.

On the “Configure Identifiers” page of the wizard, enter the unique identifier for the relying party application in the text box and click “Add”.  This is the value of the “ida:Wtrealm” key in the appsettings of your web.config file.  In the example application shown earlier, this value is “https://uniqueappid.com”.

Next, highlight the default identifier that was added from the previous screen.  In the example this is “https://localhost:44302/”.  Then click the “Remove” button, so only the proper unique identifier is left in the “Relying party trust identifiers” list.

Click Next.

On the “Choose Access Control Policy” page of the wizard, leave the default “Permit Everyone” selection and click “Next”.

On the “Ready to Add Trust” page, you can review the values on the “Identifiers” and “Endpoints” tabs, and click “Next”.

On the “Finish” page of the wizard, leave the checkbox selected and click “Close”.

The Relying Party Trust is created and visible.  Right click on it and select “Edit Claim Issuance Policy”.  This is where you will configure the claims that will be returned to the relying party after the user is authenticated by ADFS.

On the dialog that opens, click “Add Rule” at the bottom.

Select “Send LDAP Attributes as Claims” in the drop down for the Claim Rule Template.  Click Next.

On the “Configure Claim Rule” page, give the rule a name at the top.

In the “Attribute store” drop down list, select “Active Directory”.

Select the LDAP attributes “Display-Name” and “User-Principal-Name”, and assign them values in the right side drop down lists of “Name” and “UPN”, respectively.  Ensure the screen looks like the image below and click “Finish”.

On the “Issuance Transform Rules” page, click “OK” to finish creating the claims rule.

Back on the computer running Visual Studio, run the application by hitting F5 or “Start Debugging” from the Debug menu.

The application will open in the browser, and redirect to the ADFS login page.  Enter the credentials of a user in your Active Directory.

ADFS will redirect the browser back to the home page of the relying party application, where the code will display the claims you configured in ADFS.