• Source

This afternoon my good friend Pranav Rastogi pointed out that we don’t have a walkthrough showing how to use the On-Premises option for organizational authentication in the new ASP.NET project templates in VS2013 – AKA hooking up your web app to an ADFS instance.
You know what? He was right! With all the excitement around the new capabilities for cloud-based project, we didn’t cover this specific feature as that is largely a refactoring of what was already available in the Identity and Access tools in VS2012 (and before that, the venerable fedutil.exe from WIF 1.0).

Well, that’s easily fixed. This afternoon I spend 10 mins (of a meeting I wasn’t leading ) going through the process, taking screenshots of the salient steps, and tonight I’ll add a bit of descriptions to walk you though the process. Here we go!

Creating an MVC Project Secured by ADFS

Let’s start by creating an MVC project. Start VS2013, create a new project, and select the Web templates. True to the One ASP.NET spirit, you’ll see that you have only one project type to pick. Choose a name you like and hit OK.

Select “MVC” in the subtemplate screen, then hit “Change Authentication”.

Select Organizational Accounts from the options on the left, then click on the top combo box.

As you can see, you a presented with a number of possible organizations you might want to connect your application to.

• Cloud – Single Organization is meant for LoB apps tied to a Windows Azure AD tenant; this post has one example that uses this template as starting point
• Cloud – Multiple Organizations is for SaaS applications intended to be used by multiple organizations with their own Windows Azure AD tenants; walkthrough here
• On-Premises, the option we want to explore today, allows you to connect to any WS-Federation provider which offers a metadata document. Note that YMMV for any provider other than ADFS, as our testing focused on the latter.

Select “On-Premises”.

The screen asks you for two pieces of information:

• “On-Premises Authority” – this represents the URL of the metadata document of your authority. You’ll typically receive this value from your administrator. The template tool will use that document for discovering all of the relevant info about your ADFS (addresses, signing keys, identifiers, etc) and derive the project’s configuration from it
• “App ID URI” – This is, in good ol’ws-fed terms, the realm of your applicaton. You can leave it blank, and the tool will fill it up for you (with the URL assigned to your project by IIS (express)). Personally I find it is good practice to assign to your project something that helps me to remember what the app is about, even when I deploy it out of my dev environment, but that’s totally up to you. Also remember, this is a URI not an URL .
  There is another case in which you might want to enter a value here, and that’s when your administrator already provisioned the app in ADFS: in that case, you want to enter here the same realm value he/she entered in ADFS. This will get clearer in the next section.

That’s it. “OK” your way through the various dialogs back to Visual Studio, and you’ll find yourself with a nicely configured MVC app – ready to hit ADFS. However we are not ready to run yet! Before we’re able to do so, we must pay a visit to ADFS and provision our app in it.

Provisioning your Web App in ADFS

Whereas the “Cloud” options in the template can automatically provision your app in Windows Azure AD using the Graph API, for ADFS there is no such option. You have to get in touch with your administrator, and convince him/her to provision your application in the ADFS instance. In ADFS parlance, that’s called provisioning a Relying Party Trust. Until that does not happen, ADFS will NOT act on any token request it will receive from your application.

Here I’ll assume that you are an admin on your target ADFS instance. Log in on the box where ADFS is running. From the Server Manager dashboard, launch the ADFS MMC by choosing “Tools->AD FS Management”.

Take a look on the right pane, you’ll find a shortcut for “Add Relying Party Trust…”.

The process is pretty straightforward, ADFS guides you though it. Hit “Start”.

Choose “Enter data about the relying party manually”.

n the first screen you can write whatever and hit next, just remember that you never know what ends up in production 

The next screen asks for the URL of your application. That’s easy to find out: switch back to Visual Studio, select the project in the project explorer, and take a look at the properties page (usually in the bottom right corner). There you should  see the HTTPS address of your app, copy it to the clipboard.

Check the “Enable support for the WS-Federation passive protocol”, and paste the app URL in the corresponding text box. Hit next.

Here there’s where you specify the realm of your application. If you did not choose a custom realm, you are already done here. If you did, you have to paste it in and hit Add.

Done that, hit next as many times as it is necessary (without changing any of the defaults) to reach the Finish step.

At this point your app is known to ADFS – but we’re not done yet. Here’s why. Whereas Windows Azure AD features a default set of claims that are issued at sign in time, ADFS does not issue ANY claims without your direct configuration. Luckily setting something up is super fast. Click “Close”.

You are presented with another dialog which helps you to set up some claims issuance rule. Stay on this tab and hit Add Rule.

Keep LDAP as the choice, and hit Next.

Name your rule, select Active Directory ad the attribute store, and go wild with the claims you want to issue. I always suggest to ensure you are issuing at least one “Name” claim, given that often web apps use that claim for display purposes (the ASP.NET template is not exception) but that’s really up to you.

Once you are satisfied, hit Finish and get back to the MMC. Now we’re ready to run!

Running the Project

Get back in VS and hit F5.

What you see above is the somewhat garish ADFS authentication UI that my friends in the ADFS team use for showing off the customization features of the product. In this case I have the choice of using contoso as an IdP or go through a federated partner, but that’s just how this specific instance is configured. Your instance is likely to show directly the screen that I can reach by hitting on the “Contoso 100 Corp” tile.

Here I can enter my credentials, hit “Sign in” aaaaand…

…voila’! I am signed in using my local ADFS, and without having written a single line of code. If that seems long, that’s because I blabbered: just look at the screenshots, and you’ll get a feeling of how fast you can get this scenario up & running. Try it yourself and let us know if you have any questions!