Claims Based Authentication - Setting up Visual Studio 2012 on Localhost to use ADFS

So currently I'm  learning Windows Identity Foundation to do Claims Based Authentication. I'm working an a few posts on the subject and i'll be posting them soon. For now this one focuses on the my need to configure my Visual Studio environment to use my domain ADFS server as a STS. Now I know i can setup a local STS project for testing but I wanted to use our domain ADFS so that everything as close as possible to production configuration as I could for testing.

Turns out this isn’t hard to do but a few configuration steps that are easy to miss. Since I didn't find any guides or posts on how to do this I figured I’d share mine.

Overview

The end result will be a ADFS relaying service provider that will expect inbound connection from https://localhost and a Visual studio configuration set to use IIS, rather than IIS express, hosting the VS Project. What's really interesting is that since i configured this to use https://localhost any developer can use the the same relaying party for their testing rather than creating a Replaying Party Entry in ADFS for every developer machine. Also because the links will only work from the localhost you don’t need to worry about them deploying projects using that Replying Party entry because it won’t work.

Solution

There are two sides of this setup. First I’ll cover the settings I configured on the ADFS with a relaying relaying party and this those of the client machine running Visual studio.

ADFS Configuration

From the ADFS server navigate to the Relying Party Trusts and add a new Relaying Party Trust. We need to supply a FederationMetadata.xml file. I modified this one for our use. Create a text file and copy the contents to it and save it as “Localhost_FederationMetadata.xml”

Localhost_FederationMetadata.xml

<?xml version="1.0" encoding="utf-8"?>
<EntityDescriptor ID="_3d1176b1-236d-4675-8970-674b061daf17" 
                entityID="https://localhost/"
                xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
    <RoleDescriptor xsi:type="fed:ApplicationServiceType" 
                xmlns:fed="http://docs.oasis-open.org/wsfed/federation/200706"
                protocolSupportEnumeration="http://docs.oasis-open.org/wsfed/federation/200706"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <fed:TargetScopes><wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
            <wsa:Address>https://localhost/</wsa:Address></wsa:EndpointReference>
        </fed:TargetScopes>
        <fed:PassiveRequestorEndpoint>
            <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
                <wsa:Address>https://localhost/</wsa:Address>
            </wsa:EndpointReference>
        </fed:PassiveRequestorEndpoint>
    </RoleDescriptor>
</EntityDescriptor>

With the file created Choose “Import data about the relying party from a file”.






Give a descriptive name for its use.


Allow anyone to use the Relying Party.



Check the settings look correct and continue.

Now right Click the Relying Party you just entered and Edit the claim rules. You can set these up however you need for your needs but here is mine for testing.



We should be finished setting up ADFS and now setup our Windows client with Visual Studio to test.

Technorati Tags: Claims Based Authentication,ADFS,WIF,STS,Visual Studio,C#

So normally we create a Web project in Visual studio and just debug in IIS Express. Its easy and normally this is perfect. However for the purpose of using ADFS as a STS we need to have a static address, and be hosted on HTTPS. We need the host URL address to be static because the ADFS must know the URL to send the User back to after issuing a token. And the HTTPS requirement is because because it is the only thing that makes sense for a security token service (STS) is to be secure over SSL. Now you can configure IIS Express to use HTTPS but i had issues with it at the time was figuring this stuff out. but if you want to try i found a post on it (Here) after the fact that may help.

Installing IIS on Windows Client

Instead I added the IIS roles to my machine and hosted the pages on it instead of IIS Express. To do this “Open Add and Remove Programs” and on the left click “Turn Windows Features on and Off”. From my Windows 8 machine here's an example of the features I needed installed.



Once that's finished installing check that http://localhost works correctly. Now open IIS Manager. (Note the command is “inetmgr”). Now we want to add the Binding to enable HTTPS traffic for the default Website “https://localhost/”.

Expand the connections till you see the Default Web Site. Right click and click “Edit Bindings...”



Now add a binding for HTTPS, leave the hostname empty, and you can Reuse the IIS Express Certificate.



Now test that https://localhost works. If so we can open our Visual Studio Project.

Visual Studio 2012 Configuration

For my project I'm using MVC 4.5 in Visual Studio 2012 which means i can use the “Identity and Access Tool” which is pretty much by Vittorio Bertocci. By the way if you're reading this and don’t know who Vittorio Bertocci please stop reading my stuff and check his out. He quite literally wrote the book on Claims based Authentication which is Programming Windows Identity Foundation (Dev - Pro), which is what I've been reading lately.

Now if your project isn’t .Net 4.5 you can still edit your configuration file to work of course but for the example here I'm going to show with the tool. For testing create a test project in .Net 4.5 and install the “Identity and Access Tool” just to see how the tool alters the “web.config” file if nothing else.

You can create a new project but for our purposes it’s easier to start with a template already configured to use Claims rather than the default templates.

Best Template I've seen to start from is this “Claims Aware MVC Application”. Download that and extract it and open the project in Visual Studio 2012.

Once the project is created right click the project and click the “Identity and Access...” near the bottom.



This will open the tool and make the following changes under the Providers Tab..

• Change the Providers to select “Use a business identity provider (e.g. ADFS2)”
• Change the path to the STS metadata document to use your ADFS document. Be sure you test the link in a browser, if its correct it will open an XML file.
• https://<ADFS_SERVER>/FederationMetadata/2007-06/FederationMetadata.xml
• Change the Realm for the Application
• https://localhost/

Now under the Configuration Tab change the the following:

• Change the Realm for your application
• https://localhost/
• Change the Audience Uri for your application
• https://localhost/

Now we have to configure the project to use the Local IIS server with HTTPS. Right Click the project and chose the properties. Navigate to the Web section and uncheck the “Use IIS Express” and change the URL to https://localhost/ and click the Create Virtual Directory.



The Create Virtual Directory button will remap IIS to use your Project as the virtual directory root. Note if you have it mapped to a different directory it will ask if you want to remap the URL. Note that if you have multiple projects that have mapped to the same folder only the last one opened or that you click the Create Virtual Directory button will work.



Now build the project and and start the debugger. This should start the project in IIS and open the web page in a browser.



Click the Admin Tab at the top. You should be directed to require a login page.



Click the Login button. This will trigger a login into the ADFS. After you login into it you will be redirected back to the admin page now with the Token with the issued claims. If all that happened correctly you’ll be shown the Admin Page now with following information about your self.



Congratulations! You’ve just successfully installed and setup Visual Studio to debug a project configured use ADFS. Of course there's about about million other steps and additional features to add. I’ll post additional stuff soon.

Common Troubleshooting

If you're having trouble with ADFS its very useful to debug the Web Traffic with fiddler.

If you are getting “Cannot read configuration file due to insufficient permissions” when you open the website. Its most likely the IIS service read the file because the permissions on the file. Check that “(LocalMachine)\Users” has read access.

Leave a comment if you have some questions.