Hands-On LabFederated Authentication in a Windows Azure Web Role ApplicationLab version: 1.0.0

Last updated: 5/8/2023

CONTENTS

OVERVIEW................................................................................................................................................. 3

EXERCISE 1: ENABLING FEDERATED AUTHENTICATION FOR ASP.NET APPLICATIONS IN WINDOWS AZURE................................................................................................................................... 11

Task 1 – Creating a Cloud Service Project and Preparing it for Using Windows Identity Foundation 12

Task 2 - Creating a Local Development STS........................................................................................23

Task 3 – Establish a trust relationship between the web role and the development STS..................25

Task 4 –Testing FabrikamAir in the DevFabric...................................................................................31

Task 5 – Deploying FabrikamAir in the Cloud and Testing it in Staging and Production....................35

Task 6 – Deploying CloudFabrikamAir in the Cloud and Testing it in Staging and Production...........37

SUMMARY................................................................................................................................................ 51

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 though 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.

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 for the Windows Azure Platform. 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 DevFabric, a hosting environment that can be used for local simulation of execution in the fabric. The DevFabric 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 developer portal. As of today developers need to redeem an invitation token in order to be able to deploy their test project in the cloud: tokens can be currently requested at no charge at http://go.microsoft.com/fwlink/?LinkID=129453.

You can find further information at http://www.microsoft.com/azure/windowsazure.mspx.

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 Development Fabric

[optional] Deploy the Cloud Service 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

Microsoft® .NET Framework 3.5 SP2

Microsoft® Visual Studio 2008 SP1

Microsoft® Windows Identity Foundation Runtime

Microsoft® Windows Identity Foundation SDK

Windows Azure SDK

Windows Azure Tools for Microsoft Visual Studio July 2009 CTP

Setup

To prepare your computer for this guide, in Windows Explorer, browse to the Setup folder in the installation location of the guide, right-click SetupLab.cmd and choose Run as administrator. The Configuration Wizard will be launched to check if the Lab prerequisites are correctly installed. If everything is Ok, the installer for the Visual Studio code snippets used throughout the guide and the script installer for the certificates required for SSL will be executed.

Note: You must execute the SetupLab.cmd procedure with administrative privileges. 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.

The following are the steps to set up the Visual Studio snippets.

1. When prompted, choose all items in the installer.

Figure 1

Code snippets for exercise

2. A dialog window appears warning that the file is not signed; choose Yes to proceed anyway.

Figure 2Warning dialog window

3. When prompted for the location of the snippets, highlight all snippets, click the check box next to My Code Snippets, and click Next.

Figure 3Installation location for code snippets

4. When prompted for the location of the XML snippets, highlight all snippets, click the check box next to My XML Snippets, and click Next.

Figure 4Installation location for XML snippets

5. Click Next to continue.

Figure 5Installation confirmation for lab snippets

6. Click Finish.

7. The installation should proceed and install all snippets.

Figure 6Installation confirmation

Using the Code Snippets

With code snippets you have all the code you need at your fingertips. The lab document will tell you exactly when you can use them. For example,

1. Add the following using directives.

(Code Snippet – Federated Authentication for WebRole Guide – UsingCodeSnippets)

C#

using System.Linq;using System.Threading;using Microsoft.IdentityModel.Claims;

To add this code snippet in Visual Studio you simply place the cursor where you would like the code to be inserted, start typing the snippet name, in this case Federated Authentication for WebRole Guide - UsingCodeSnippets, watch as Intellisense picks up the snippet name, and hit the TAB key twice once the snippet you want is selected. The code will be inserted at the cursor location.

To insert a code snippet using the mouse rather than the keyboard (i.e. for web.config file and any other XML document), right-click where you want the code snippet to be inserted, select Insert Snippet, then My Code Snippets and then select the relevant snippet.

To learn more about Visual Studio IntelliSense Code Snippets, including how to create your own, please see http://msdn.microsoft.com/en-us/library/ms165392.aspx.

Exercises

This Hands-On Lab comprises the following exercise:

1. Enabling Federated Authentication in Windows Azure

Estimated time to complete this lab: 60 minutes.

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 (DevFabric, 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 Cloud Service project in order to work in the DevFabric 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 7A 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 Cloud Service Project and Preparing it for Using Windows Identity Foundation

1. Open Microsoft Visual Studio 2008 with administrator privileges. In Start | All Programs | Microsoft Visual Studio 2008, right-click Microsoft Visual Studio 2008 and select Run as administrator.

2. In the File menu, choose New and then Project.

3. In the New Project dialog, select Cloud Service in the project types list.

4. In the Templates list, select Windows Azure Cloud Service. 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 %YourInstallationFolder%\Labs\WindowsAzureAndPassiveFederation\Source\Ex1-AzureFederatedAuthentication\ folder. Ensure Create directory for solution is checked. Click OK to create the project.

Figure 8Creating a new Web Cloud Service

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 screenshots, the hands-on uses the name fabrikamair. Substitute your own project name when following a procedure.

5. In the New Cloud Service 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 cloud service solution.

Figure 9Assigning roles to the cloud service project

6. 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 2008 | Visual Studio Tools, right-click Visual Studio 2008 Command Prompt and choose Run as administrator.

7. Change the current directory to the %YourInstallationFolder%\Labs\WindowsAzureAndPassiveFederation\Source\Assets folder, where %YourInstallationFolder% is the installation folder of the lab, 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 fabrikamair

While running the script you will be asked to enter a password to secure your private key, type abc!123 and press OK.

Figure 10Specifying 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 11Adding a certificate as a trusted root

8. Go to the Solution Explorer, navigate to <yourproject>/Roles/FederatedIdentity_WebRole. Right click on it and choose Properties

Figure 12Modifying FederatedIdentity_Webrole properties

9. Go to the Configuration Tab and click on the Full Trust radio button.

Figure 13FederatedIdentity_WebRole is set to full trust so WIF work as expected

Why do you need to set Enable Full Trust to True?

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.

10. Go to the Certificates Tab and click on Add Certificate.

Figure 14Selecting Add Certificate

11. Type your <projectName> in the Name field and click on the Thumbprint column to select the cert you generated in step 12.

Figure 15Selecting the certificate previously added

12. In the Endpoints tab disable the HTTP endpoint, activate the HTTPS endpoint and select your certificate in SSL certificate name

Figure 16Enabling Https

13. Go to Solution Explorer, right-click the FederatedIdentity_WebRole project and choose Add Reference. In the .NET tab, select Microsoft.IdentityModel and click OK.

14. Go to the References folder for the FederatedIdentity_WebRole project, select Microsoft.IdentityModel. Press F4 to open the Properties window and set Copy Local to True and Specific Version to False.

Why do you need to set Copy Local to True for the reference to Microsoft.IdentityModel?Microsoft.IdentityModel is the main Windows Identity Foundation assembly. As mentioned above, such assembly is not available in the Global Assembly Cache that is visible to Windows Azure applications. By setting its Copy Local property to True, you ensure that the bits of the

assembly will be included in the project package. Therefore, once you deploy it in the cloud, this will ensure that the WIF is deployed too and available to your application.

15. Update the using statements into Default.aspx.cs in FederatedIdentity_WebRole.

(Code Snippet – Federated Authentication for WebRole Guide – RP Usings)

C#

using System;using System.Collections.Generic;using System.Linq;using System.Web;using System.Web.UI;using System.Web.UI.WebControls;using Microsoft.IdentityModel.Claims;using System.Threading;

16. Insert the following code into the body of the Page_Load handler Default.aspx.cs in FederatedIdentity_WebRole.

(Code Snippet – Federated Authentication for WebRole Guide – RP Page_Load Body)

C#

namespace FederatedIdentity_WebRole{ public partial class _Default : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { IClaimsPrincipal icp = Thread.CurrentPrincipal as IClaimsPrincipal; IClaimsIdentity ici = icp.Identity as IClaimsIdentity; Response.Write("Welcome to Fabrikamair <br/><br/>:Claims:<br/>"); foreach (Claim c in ici.Claims) Response.Write(c.ClaimType + "-" + c.Value + "<br/>"); } }}

17. Go to Solution Explorer, right-click the FederatedIdentity_WebRole project and choose Add | New Item. Choose Global Application Class and click Add.

18. Double-click the Global.asax file you just added. Replace the current using statements with the following:

(Code Snippet – Federated Authentication for WebRole Guide – RP Global.asax Using)

C#

using System;using System.Collections.Generic;using System.Web;using System.Text;using Microsoft.IdentityModel.Tokens;using Microsoft.IdentityModel.Web;using Microsoft.IdentityModel.Web.Configuration;

19. Add the WSFederationAuthenticationModule_RedirectingToIdentityProvider method as follows:

(Code Snippet – Federated Authentication for WebRole Guide – RP Global.asax RedirectingToIdentityProvider)

C#

public class Global : System.Web.HttpApplication{ ... /// <summary> /// Retrieves the address that was used in the browser for accessing /// the web application, and injects it as WREPLY parameter in the /// request to the STS /// </summary> void WSFederationAuthenticationModule_RedirectingToIdentityProvider(object sender, RedirectingToIdentityProviderEventArgs e) { // // In the Windows Azure environment, build a wreply parameter for the SignIn request // that reflects the real address of the application. // HttpRequest request = HttpContext.Current.Request; Uri requestUrl = request.Url; StringBuilder wreply = new StringBuilder();

wreply.Append(requestUrl.Scheme); // e.g. "http" or "https" wreply.Append("://"); wreply.Append(request.Headers["Host"] ?? requestUrl.Authority); wreply.Append(request.ApplicationPath);

if (!request.ApplicationPath.EndsWith("/")) wreply.Append("/");

e.SignInRequestMessage.Reply = wreply.ToString(); }...}

What is the WSFederationAuthenticationModule_RedirectingToIdentityProvidermethod for?

The federated sign on process implemented by WIF is based on the WS-Federation protocol. Unauthenticated users landing on the web site are redirected to the trusted STS for authentication and token issuance. The URI used for the redirection contains a number of parameters, mainly retrieved from the website Web.config: among those, there is the address to which the STS will have to redirect the user’s browser once successfully authenticated. In the default case, WIF retrieves that return address from the configuration settings generated by the Federation Utility wizard.

In Windows Azure this approach would not work as is: an application hosted in Windows Azure will have a different URI depending on the environment in which it is hosted (DevFabric, staging, production) hence one would have to continuously change the values in the Web.config before deploying. In fact, even that strategy would not work in all cases since in the staging environment you learn what URI has been assigned to your app only AFTER you deployed the project.

The current solution to this is finding out at runtime what the address of the app is, and injecting it in the request to the STS as wreply parameter. An STS receiving a wreply would use its value as the return address, hence decoupling your application from its address at deploy time.

Of course, there are many security considerations to be made about this solution. To name one, this will often lead to a red address bar in Internet Explorer, since the subject of the certificate used to secure the website will match the URI only when the project is deployed in the production environment. Furthermore, this opens the door to redirect attacks that will have to be mitigated at the STS side.

Why do you use the Host header instead of just getting the Uri from HttpContext.Current.Request.Url?

Windows Azure uses various network artifacts in its infrastructure: as a result, the Url property of the current http request would contain ports that are not really meaningful outside Windows Azure internals and that would cause problems, for example mess up with session cookies. The code provided ensures that the URI in the browser address bar will be used.

20. On the Global.asax.cs file, add the OnServiceConfigurationCreated method.

(Code Snippet – Federated Authentication for WebRole Guide – RP Global.asax ServiceConfiguration_Created)

C#

public class Global : System.Web.HttpApplication{ ... void OnServiceConfigurationCreated(object sender, ServiceConfigurationCreatedEventArgs e) { // // Use the <serviceCertificate> to protect the cookies that are sent to the client. // List<CookieTransform> sessionTransforms = new List<CookieTransform>(new CookieTransform[] { new DeflateCookieTransform(), new RsaEncryptionCookieTransform(e.ServiceConfiguration.ServiceCertificate) }); SessionSecurityTokenHandler sessionHandler = new SessionSecurityTokenHandler(sessionTransforms.AsReadOnly());

e.ServiceConfiguration.SecurityTokenHandlers.AddOrReplace(sessionHandler); } ...}

What does ServiceConfigurationCreated do?

By default WIF SessionTokens use DPAPI to protect the content of Cookies that it sends to the client, however DPAPI is not available in Windows Azure hence you must use an alternative mechanism. In this case, we rely on RsaEncryptionCookieTransform, which we use for encrypting the cookies with the same certificate we are using for SSL in our website.

21. On the Global.asax.cs file, register the OnServiceConfigurationCreated handler in the Application_Start method.

(Code Snippet – Federated Authentication for WebRole Guide – RP Global.asax Application_Start)

C#

...public class Global : System.Web.HttpApplication{ ... protected void Application_Start(object sender, EventArgs e)

{ FederatedAuthentication.ServiceConfigurationCreated += OnServiceConfigurationCreated; } ...}

Task 2 – Creating a Local Development STS

1. Right click on the solution and choose Add | New Web Site. Pick ASP.NET Security Token Service Web Site. Choose location HTTP, specify https://localhost/[yourprojectname]_sts to create it on your local IIS and click OK.

Figure 17Creating your local STS website

2. Open CustomSecurityTokenService.cs in https://localhost/[yourprojectname]_sts/App_Code. Add the following method to the CustomSecurityTokenService class, just above GetScope.

(Code Snippet – Federated Authentication for WebRole Guide – STS ValidateReplyTo)

C#

public class CustomSecurityTokenService : SecurityTokenService{ ...

/// <summary> /// Validates replyTo and throws an exception if the replyTo refers to a /// RP that is not on the local machine or is not hosted in Windows Azure /// </summary> /// <param name="replyTo"> /// The replyTo parameter in the request that came in (RST) /// </param> void ValidateReplyTo(string replyTo) { // if ReplyTo is empty, we have nothing to validate. We will default // to AppliesTo, which is harder to compromise via redirect attack if (!String.IsNullOrEmpty(replyTo)) { string host = (new Uri(replyTo)).Host.ToLower(); if (!((host == "127.0.0.1") || (host == "localhost") || host.EndsWith(".cloudapp.net"))) { throw new InvalidRequestException( String.Format( "The host in the ReplyTo address {0} is not valid.", host)); } } } protected override Scope GetScope( IClaimsPrincipal principal, RequestSecurityToken request) {

...}

3. At the beginning of GetScope, add a call to ValidateReplyTo that was added in the previous step.

(Code Snippet – Federated Authentication for WebRole Guide – ValidateReplyTo Call)

C#

...protected override Scope GetScope( IClaimsPrincipal principal, RequestSecurityToken request){ ValidateAppliesTo( request.AppliesTo ); ValidateReplyTo(request.ReplyTo);

Scope scope = new Scope( request.AppliesTo.Uri.OriginalString, SecurityTokenServiceConfiguration.SigningCredentials);...

4. At the end of GetScope, comment the current scope.ReplyToAddress assignment and replace it with the following code.

(Code Snippet – Federated Authentication for WebRole Guide – STS Redirect to ReplyTo)

C#

protected override Scope GetScope( IClaimsPrincipal principal, RequestSecurityToken request){ ... // Set the ReplyTo address for the WS-Federation passive protocol (wreply). // This is the address to which responses will be directed. // In this template, we have chosen to set this to the AppliesToAddress. //scope.ReplyToAddress = scope.AppliesToAddress;

// If we receive a wreply from the RP we use it: otherwise we default // to AppliesTo. Note that a wreply that would make it to this line // would have been validated by ValidateReplyTo scope.ReplyToAddress = String.IsNullOrEmpty(request.ReplyTo) ? scope.AppliesToAddress : request.ReplyTo;

return scope;}

Why do we make those changes to the default local STS auto-generated by the Federation Utility wizard?

In Task 1, you modified the Global.asax of your application to ensure that it would send its actual URI to the STS, by storing it in the wreply parameter.

The ValidateReplyTo ensures that the address in the wreply refers to an application on your local machine (as in the DevFabric case) or from a host ending with “.cloudapp.net” (as in the Windows Azure staging or production environments case). This mitigates redirection attacks, as it limits the accepted ReplyTo values to addresses of Windows Azure applications. Note that this check would prevent you from using a domain name not matching the Windows Azure schema; hence, if you plan to map Windows Azure applications through a custom domain, you will have to adjust the code accordingly.

The assignment of scope.ReplyToAddress is modified to take the value of wreply, if present. If no wreply parameter is available in the request, the assignment will fold back to the default behavior (using the AppliesTo uri).

Task 3 – Establish a trust relationship between the web role and the development STS

1. Go to Solution Explorer, right-click the FederatedIdentity_WebRole project and choose Add STS reference. Accept the proposed location for the application configuration file, set the Application URI to https://<yourProjectName>.cloudapp.net, where <yourProjectName> is the name chosen for your cloud project (e.g. https://fabrikamair.cloudapp.net/) and click Next.

Figure 18The first screen of the Federation Utility wizard

2. Select the option Use an existing STS, browse to %your inetpub folder%\wwwroot\<yourProjectName>_sts\FederationMetadata\2007-06\, select the file FederationMetadata.xml and click Next.

Figure 19The second screen of the Federation Utility wizard

3. Select the option No encryption and click Next.

Figure 20Federation encryption setup screen

4. Click Next.

Figure 21Claim offered by the STS.

5. On the summary page review the changes that will be made and click Finish.

Figure 22Summary

6. Add the serviceCertificate element in the Web.config of the FederatedIdentity_Webrole project under microsoft.identityModel\service. You can find the corresponding thumbprint in the ServiceConfiguration.cscfg file.

(Code Snippet – Federated Authentication for WebRole Guide – ServiceCertificate)

XML

<microsoft.identityModel> <service> ... <serviceCertificate> <certificateReference x509FindType="FindByThumbprint" findValue="[yourCorrespondingThumbprint]"/> </serviceCertificate> </service></microsoft.identityModel>

7. Add the certificateValidation element under the microsoft.identityModel\service element and set the certificateValidationMode attribute to None.

(Code Snippet – Federated Authentication for WebRole Guide – CertificateValidation)

XML

<microsoft.identityModel> <service> ... </serviceCertificate> <certificateValidation certificateValidationMode="None"/> </service></microsoft.identityModel>

Note: We expect the token we receive to be signed with the private key of the STS we trust. The Add STS Reference wizard we went through in steps 1 to 5 saved in the element issuerNameRegistry of web.config the thumbprint of the certificate of the STS we trust. Once we receive a token, WIF uses this information for:

- Retrieving the corresponding certificate

- Using the certificate for checking the token signature

- Verifying that the signer was indeed listed in the issuerNameRegistry element, hence trusted

In order to perform those operations, WIF can use the thumbprint for retrieving the bits of the STS certificate from the certificate store. However, certificate handling in Windows Azure requires extra operations, hence here we use an alternative method. Very often the request containing the token will also contain the bits of the certificate corresponding to the signature: this means that our application can use the thumbprint for retrieving the certificate from the request itself rather than relying on having the bits available locally. Setting the certificateValidationMode to None has the purpose of enabling the latter scenario.

Note that the request does not have to contain the bits of the certificate, and for certain platforms this won’t be the default behavior: in those cases you will need to deploy in Windows Azure the public key (that is to say the certificate) of the STS as well, as shown in step 9 of task 6.

Task 4 –Testing FabrikamAir in the DevFabric

Figure 23In this task you will run the web application in the DevFabric, while the development STS we created in Task 2 will take care of authenticating users while running in the local IIS

1. You are finally ready to test the application in the DevFabric. Set the cloud project as the start up project. To do this, in Solution Explorer, right-click fabrikamair project and choose Set as StartUp Project.

2. Press F5 to build and run the application. A browser page will open, pointing to https://127.0.0.1:444 (or some other random available port that DevFabric assigns). In the first screen, you will observe a certificate warning because the DevFabric uses an IP address for navigating to your application, while the certificate you are using refers to the address that the application will have once deployed in production in the cloud. Click Continue to this website.

Figure 24The browser informs us that there is a discrepancy between the page address and the subject of the certificate used for the SSL binding: this is expected given the way in which DevFabric handles addresses

You will be redirected to the local STS page that is hosted on your local IIS. Click Submit.

Figure 25The default authentication page presented by local STS. Note the address bar: the STS still runs on the local IIS

3. The STS issues the token and redirects to the Web Role application hosted in the DevFabric; WIF validates the token and grants the user access to the site. The red address bar once again indicates that the certificate you are using is already the one you will use in the cloud, hence the subject does not correspond to the URL shown in the browser. Close the browser and go back to Visual Studio.

Figure 26The web application hosted in the DevFabric successfully authenticated the user, and correctly processed the incoming token as shown on the page. The address bar is red, as expected for applications in the DevFabric

Task 5 – Deploying FabrikamAir in the Cloud and Testing it in Staging and Production

In order to be able to run this lab on Windows Azure you register to obtain a Windows Azure developer account. This is an optional task; you can skip it and the lab would be completed.

Note: if you already have a windows Azure account you can use it and skip this exercise.

In this task, you create a new Windows Azure account and redeem an invitation token to enable the creation of hosted services.

1. Navigate to http://windows.azure.com using a Web browser and sign in using your Windows Live ID.

Figure 27Signing in to the Windows Azure portal

2. If this is your first visit to the Windows Azure Developer Portal, create a new account associated to your Windows Live ID. Review the Privacy Statement and click I Agree to proceed.

Figure 28Creating a new Windows Azure Developer Portal account

3. After creating the account, click Continue to proceed.

Figure 29

Successful creation of the account

4. Enter your invitation token and click Next to redeem it.

Note: Invitation tokens are required to enable services at the Windows Azure Developer Portal. To obtain an invitation token, you will need to register at http://connect.microsoft.com to obtain a product key for the Windows Azure Platform.

Figure 30Redeeming an invitation token to enable the creation of hosted services

Task 6 – Deploying CloudFabrikamAir in the Cloud and Testing it in Staging and Production

Now that you verified that the application works as expected in the DevFabric, you are ready to deploy it to the cloud and test it there.

Figure 31In this task you will publish your project to the staging environment, test it, and finally move it to the production environment

Note: Please remember that to be able to deploy in the cloud you need an account on the Windows Azure development portal and an invitation token for creating Hosted Services.

The steps 4, 5 and 6 assume that you comply with the above requirements, that you have a project in place but that you did not create a service for this application yet, hence walk you through the project creation procedure. If you already have a project in which you want to deploy the current application, you can skip to step 5.

5. Click the Project Name of the project you want to use for hosting your service, then click New Service on the top left corner.

Figure 32Create a new service

6. Choose Hosted Services.

Figure 33Pick Hosted Services

7. Assign a Label and a Description to your service component and click Next.

Figure 34Service component name and description

8. Type the intended name of your project (in this case fabrikamair) in the Service Name field and verify it is available by clicking Check Availability. If it is available, click Create.

Figure 35Claim the service URL and establish its affinity group

9. Before we can upload our package to the cloud, we need to ensure that our target environment will have all the certificates it needs for allowing our application to function as expected.

Note: In step 11 of task 1 we picked a certificate from the local certificate store to act as the SSL certificate for our application. Now that we are preparing to deploy our application to the cloud, we need to ensure that the certificate and its private key will be available in our target deployment environment. Note that in this lab we do not take advantage of token encryption: if we did, we would have to decide if we want to decrypt tokens with the same certificate we use for SSL (in which case we would already be all set) or if we would want to use another one. In the latter case, we would need to repeat the steps 10 to 13 below for uploading the pfx encrypting certificate and its private key.

Trust management via STS certificates requires some specific considerations: see the note in step 7 of task 3.

10. Click on Manage on the Certificates section.

Figure 36Manage certificates

11. Click on Browse to select the SSL certificate created on Task 1, Step 7.

Figure 37Select the SSL certificate to upload

12. Navigate to the folder where the certificate was created %YourInstallationFolder%\Labs\WindowsAzureAndPassiveFederation\Source\Assets\certs and select the file called <yourpProjectName>.cloudapp.net.pfx.

Note: Make sure to select the .pfx file extension

13. Type the password for the private key of your certificate and click on Upload.

Figure 38Private key password

Figure 39Uploaded certificate

14. Now that the certificate was uploaded we are ready to deploy the solution to Windows Azure. The certificates must be successfully deployed before uploading the solution, otherwise the solution deployment will fail. In Solution Explorer, right-click on the cloud project <yourProjectName>, and choose Publish. In this process, Visual Studio will open two windows: one containing the package and configuration file; and a browser pointing to the provisioning page of the Windows Azure portal (this may require you to authenticate using the Live ID account you registered with).

Figure 40Windows Explorer on the folder containing the packaged project files

Figure 41The Windows Azure portal

15. Deploy your project to staging. Click the Deploy button under the Staging area.

Figure 42

The hosted service as shown in the development portal before any deployment took place

16. In this page you will be prompted to select the .cspkg and .cscfg files that you generated from Visual Studio in step 1 of this task: you can find them in the file system location indicated by the Windows Explorer window that opened when you published the package. Once both file paths have been selected, enter an arbitrary label for the deployment (e.g.: the current date) in the Properties area and click Deploy.

Figure 43Deploying to staging

17. The project has been deployed in the Staging environment and has been assigned an URL of the form <GUID>.cloudapp.net. Click Run to activate the instance.

Figure 44Package deployed in Staging and ready to run

18. The application will spend some time Initializing (this might take 10 minutes at most). Once it goes into Started mode, click the Web Site URL link. A new browser will open, and you will get an error since the link is on http while you exposed only on https. Add the “s” in the address bar, and press ENTER. A certificate warning will be issued, since the staging URL, that contains a Guid, does not correspond to the certificate fabrikamair.cloudapp.net; you will be redirected to the development STS on your localhost; finally, you will land on the staging application where you will successfully authenticate.

Figure 45The web application running in Staging environment

Figure 46The Windows Azure portal showing the application ready

19. Now you are finally ready to promote the deployment to Production. Click the button between the Production and Staging areas of the project page. Click OK on the dialog with the message “Are you sure you want to promote to the production deployment?”.

Figure 47Swap from Staging to Production

Figure 48The web application running in the Production environment

20. The project is now deployed and running in production. Click the Web Site URL link. You will need to manually add an “s” in the browser address bar to change from http to https. This time you will not receive any certificate warning because the DNS name matches the certificate you uploaded. The browser will be redirected to the local STS running on your local IIS. Click Submit to authenticate. The home page of the website will show the claims issued by the STS.

Figure 49The web application running in the Production environment with an HTTPS certificate

Summary

Taking advantage of existing identities in new applications is one of the fundamental requirements in today’s distributed systems, and the new wave of cloud based services is no exception.

By completing this Hands-On Lab you have learned:

How to externalize authentication for a Windows Azure Web Role application, by taking advantage of Windows Identity Foundation for federating with an external authority (here simulated by a development STS)

[Optional] How to deploy such an application in Windows Azure and take care of the operations (such as deploying certificates) that are necessary for making the application work as expected in federated and SSO scenarios

As you have discovered while going through the lab, the claims-based approach to identity enabled by Windows Identity Foundation can be applied with little or no modification to both on-premises or cloud application.

We hope that the programming skills you learned in this and the other identity labs will enable you to write solutions with the confidence that no matter where your application will end up being deployed, you took care of identity in consistent and effective manner.