Hands-On Lab
Federated Authentication in a Windows Azure Web Role Application
Lab version: 2.0.0
Last updated: 12/1/2011
Contents
Overview 3
Exercise 1: Enabling Federated Authentication for ASP.NET applications in Windows Azure 6
Task 1 – Creating a Windows Azure Project and Preparing it for Using Windows Identity Foundation 7
Task 2 – Creating a Local Development STS 20
Task 3 – Establishing a Trust Relationship between the Web Role and the Development STS 23
Task 4 – Testing FabrikamAir in the Windows Azure Compute Emulator 30
Task 5 – Publishing CloudFabrikamAir in the Cloud and Testing it in Staging and Production 33
Summary 46
Overview
This hands-on lab provides step-by-step guides for hosting in Windows Azure (WAZ) a Web application accepting identities from an external identity provider: with the authentication functions being performed by an external identity provider, you are now free to focus on the business function of your application instead of worrying of low level details. As you will learn while you go through the lab, this is easily accomplished by taking advantage of Windows Identity Foundation (WIF), formerly known as Geneva, for enhancing your web site or web service.
The text gives very concrete indications, and it is optimized for minimizing the number of steps that are necessary for getting up and running with the minimal scenario. We will occasionally add notes in the text to explain choices rationales and indicate alternatives for the reader who is interested in understanding how the solution works or wants to explore more advanced scenarios: if all you are interested in is getting the basic scenario up and running, you can safely skip those notes as you follow the lab instructions.
Essential Introduction to Windows Identity Foundation for Windows Azure developers
Windows® Identity Foundation (WIF) is a developer framework which enhances the .NET Framework with advanced identity capabilities. Based on the concept of Claims Based access, WIF offers a series of classes that, while integrating seamlessly with the traditional .NET identity object model, gives developers control over every aspect of authentication, authorization and identity-driven application behavior. WIF point & click tooling and tight Visual Studio integration make very easy to externalize authentication to a federated partner, so that a developer can configure an ASP.NET application or a WCF service to rely on external entities for identity management. WIF allows application access using open protocols and standards, while hiding the complexity of the security plumbing behind a handy programming model. WIF will work with applications written with the .NET Framework 3.5 SP2 or higher.
You can find further information at http://www.microsoft.com/wif.
Essential Introduction to Windows Azure for Windows Identity Foundation developers
Windows® Azure is a cloud services operating system that serves as the development, service hosting and service management environment of either consumer Web or enterprise scenarios. Windows Azure provides developers with on-demand compute and storage to host, scale, and manages Web applications on the Internet through Microsoft® data centers.
Windows Azure offers a set of Visual Studio templates that can be used to develop ASP.NET applications or worker services destined to be deployed in the cloud. The Windows Azure Tool for Visual Studio includes the Windows Azure compute emulator, a hosting environment that can be used for local simulation of execution in the fabric. The Windows Azure compute emulator gives you the chance to experiment with multiple concurrent instances and other cloud features without the need to be online, while still being able to use your familiar debugging and development tools.
Windows Azure applications can be packaged via Visual Studio or command-line tooling, and then deployed in the cloud via the Windows Azure management portal.
You can find further information at http://www.microsoft.com/azure/windowsazure.mspx in order to able to deploy your project.
Objectives
In this hands-on lab, you will learn how to:
· Create a simple ASP.NET web site in a Windows Azure Web Role project, and configure it to rely on an external federated entity for authentication. The federated partner will be simulated by a local development security token service (STS).
· Test the Windows Azure Web role project in the local Windows Azure compute emulator.
· [optional] Deploy the Windows Azure project in the cloud and test it with the local development STS both from staging and production environment.
System Requirements
The following is required to complete this hands-on lab:
· Microsoft® Windows® Vista SP2 (32-bits or 64-bits) , Microsoft® Windows Server 2008 SP2 (32-bit or 64-bit), Microsoft® Windows Server 2008 R2, Microsoft® Windows® 7 RTM (32-bits or 64-bits)
· Microsoft® Internet Information Services (IIS) 7.0 with IIS Metabase and IIS 6 configuration compatibility
· Microsoft® .NET Framework 4
· Microsoft® Visual Studio 2010
· Microsoft® Windows Identity Foundation Runtime
· Microsoft® Windows Identity Foundation SDK 4.0
· Windows Azure Tools for Microsoft Visual Studio 1.6
Setup
In order to execute the exercises in this hands-on lab you need to set up your environment.
1. Open a Windows Explorer window and browse to the lab’s Source folder.
2. Double-click the Setup.cmd file in this folder to launch the setup process that will configure your environment and install the Visual Studio code snippets for this lab. This will also install the localhost certificate used by the local STS.
3. If the User Account Control dialog is shown, confirm the action to proceed.
Note: Make sure you have checked all the dependencies for this lab before running the setup.
Note: The procedure installs a self-signed certificate to enable the SSL binding. If you already have a certificate with subject name CN=localhost, you must back up the certificate and restore after completing the steps in this guide.
Using the Code Snippets
Throughout the lab document, you will be instructed to insert code blocks. For your convenience, most of that code is provided as Visual Studio Code Snippets, which you can use from within Visual Studio 2010 to avoid having to add it manually.
If you are not familiar with the Visual Studio Code Snippets, and want to learn how to use them, you can refer to the Assets\Setup.docx document in the Assets folder of the training kit, which contains a section describing how to use them.
Exercises
This hands-on lab includes the following exercise:
1. Enabling Federated Authentication in Windows Azure
Estimated time to complete this lab: 60 minutes.
Note: When you first start Visual Studio, you must select one of the predefined settings collections. Every predefined collection is designed to match a particular development style and determines window layouts, editor behavior, IntelliSense code snippets, and dialog box options. The procedures in this lab describe the actions necessary to accomplish a given task in Visual Studio when using the General Development Settings collection. If you choose a different settings collection for your development environment, there may be differences in these procedures that you need to take into account.
Exercise 1: Enabling Federated Authentication for ASP.NET applications in Windows Azure
Securing an ASP.NET web site with WIF is very simple. Within Visual Studio you right-click the project, run an easy wizard in which you indicate from which federated partner you want to accept identities, and you are done. You even have the option to generate on the fly a local development STS which can be used if you do not have federated partners available at development time.
That simple procedure remains largely unchanged even when you are targeting Windows Azure as the deployment environment for your application: the few adjustments you need to apply are mainly related to the structural features of Windows Azure, such as the way in which X509 certificates are stored or how application URIs are handled across the different environments (Windows Azure compute emulator, Staging, Production).
In the following tasks, you will see how to create a Windows Azure WebRole, configure it to use a local development STS and modify the Windows Azure project in order to work in the Windows Azure compute emulator by still referencing the local development STS. Finally, you will publish the project in the cloud and see how the application still works with the local development STS when running in the staging and production environments.
This hands-on lab demonstrates the minimal integration scenario between WIF and Windows Azure. You can easily extend what you will learn here to more realistic scenarios, such as the case in which you want to reuse on-premises identities exposed via AD FS 2.0 (formerly known as “Geneva” Server). You will discover that the process is even simpler.
Figure 1
A summary of the steps followed by this exercise. You start by creating an ASP.NET website (RP) in a Windows Azure Web Role and an STS for it in the same Visual Studio solution and you establish trust between the two. Upon successful testing you publish & test the WebRole in staging and finally in production. The STS used at all stages is the one hosted by the local IIS: this is done to simplify the deployment of this guide on dev machines, but if you have a production STS available you can certainly use it in lieu of the test one.
Task 1 – Creating a Windows Azure Project and Preparing it for Using Windows Identity Foundation
1. Open Microsoft Visual Studio 2010 with administrator privileges. In Start | All Programs | Microsoft Visual Studio 2010, right-click Microsoft Visual Studio 2010 and select Run as administrator.
2. In the File menu, choose New and then Project.
3. In the New Project dialog, select Cloud in the Templates list under Visual C# node.
4. Select Windows Azure Project as project type.
5. Choose a suitable name for your solution. Keep in mind that the name must be unique because it will be publicly visible when deployed to Windows Azure. Set the solution name “Begin” and the location to the \Source\Ex1-AzureFederatedAuthentication\ folder. Ensure Create directory for solution is checked and the framework is .NET Framework 4. Click OK to create the project.
Figure 2
Creating a new Windows Azure Project
Note: Why do we require you to choose your own project name, instead of providing a sample solution?
Every Windows Azure service is published on an URI of the form <projectname>.cloudapp.net.
The string <projectname> must be unique, since it has to be resolvable on the public internet.
For the first steps of this hand-on lab, you could technically use any project name you’d like, since all addresses will be resolved locally. You are forced to pick a unique name (and adjust the configurations accordingly) only at the moment in which you deploy your application in production.
Note: The steps in this guide are more easily understood if the naming convention is coherent, hence we suggest you adhere to it at least the first time you go through it. If you want to adapt the instructions to the name you will choose, simply apply a Find & Replace against fabrikamair on the docx version of this document. When referring to the project name in procedure steps and figures, the hands-on uses the name fabrikamair. Substitute your own project name when following a procedure.
6. In the New Windows Azure Project dialog, expand the Roles panel for Visual C#, select ASP.NET Web Role from the list of available roles and click the arrow (>) to add an instance of this role to the solution. Before closing the dialog, select the new role in the right panel, click the pencil icon and rename the role to FederatedIdentity_WebRole. Click OK to create the Windows Azure project solution.
Figure 3
Assigning roles to the Windows Azure project
7. Generate a self-signed certificate for the application to use SSL. For your convenience, the lab material includes a script that performs the necessary actions. It creates the certificate using the subject you specify, installs it to the LocalMachine/Personal certificate store and adds the certificate to the LocalMachine/Trusted Root Certification Authorities store (to avoid the certificate error warning when browsing the site with IE). Open a Visual Studio command prompt as an administrator. To do this, open Start | All Programs | Microsoft Visual Studio 2010 | Visual Studio Tools, right-click Visual Studio Command Prompt (2010) and choose Run as administrator.
8. Change the current directory to the \Source\Assets folder, and execute the CreateCert.cmd script specifying the name of your project as a parameter.
Note: VERY IMPORTANT! make sure to use lower casing for the certificate name.
For example:
Visual Studio Command Prompt
CreateCert.cmd yourprojectname
While running the script you will be asked to enter a password to secure your private key, type abc!123 and press OK.
Figure 4
Specifying a password to secure your private key
Figure 5
Specifying a password to secure your private key
When you add the certificate to the Trusted Root Certification Authorities store, you are presented with a warning. Click Yes to install the certificate.
Figure 6
Adding a certificate as a trusted root
9. Go to the Solution Explorer; navigate to <yourproject>/Roles/FederatedIdentity_WebRole. Right-click on it and choose Properties.
Figure 7
Modifying FederatedIdentity_Webrole properties
10. Go to the Configuration Tab and ensure that the Full Trust option is set.
Figure 8
FederatedIdentity_WebRole is set to full trust so WIF work as expected
Note: Why do you need to set .NET trust level to Full Trust?
Windows Identity Foundation relies on Windows Communication Foundation (WCF) for handling various cryptography and protocol related operations. Today those parts of WCF require full trust to execute correctly, hence the Enable Full Trust requirement.
Furthermore, the Windows Identity Foundation assemblies are not available in the Global Assembly Cache seen by Windows Azure projects (see below); hence partial trust execution would not be possible in any case.
11. Go to the Certificates Tab and click on Add Certificate.
Figure 9
Selecting Add Certificate
12. Type your <projectName> in the Name field and click on the Thumbprint column to select the cert you generated previously.
Figure 10
Selecting the certificate previously added
13. In the Endpoints tab, add a new Https endpoint. Click Add Endpoint, and set the following values:
◦ Name: HttpsIn
◦ Type: Input
◦ Protocol: https
◦ Public Port: 8080
◦ SSL Certificate Name: <yourprojectname>
Figure 11
Adding a Https endpoint
14. Remove the HTTP endpoint. Select the existing “Endpoint1” and click Remove Endpoint.
Figure 12
Removing the Http endpoint