Hands-On LabEnhancing an ASP.NET Membership Provider Website with Identity Provider CapabilitiesLab version: 1.0.0

Last updated: 5/25/2023

Contents

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

EXERCISE 1: ENHANCE AN ASP.NET MEMBERSHIP WEBSITE WITH IDENTITY PROVIDER CAPABILITIES AND USE IT FROM A THIRD PARTY WEBSITE.............................................................7

Task 1 - Preparing the Solutions..........................................................................................................7

Task 2 - Inspecting the Initial Solution.................................................................................................9

Task 3 - Creating the Passive STS Page...............................................................................................10

Task 4 - Creating the Partner Web Site..............................................................................................13

Task 5 - Validating the STS Issues Tokens to a Specific Relying Party.................................................20

Task 6 - Customizing Authorization with Different Roles...................................................................21

Exercise 1: Verification......................................................................................................................22

SUMMARY................................................................................................................................................ 28

Overview

Contrary to what you may have heard, reaping the benefits of claims-based identity & access management does not necessarily require any rip & replace intervention on your existing asset. In this short hands-on lab we will demonstrate how you can easily enhance a common ASP.NET membership provider website with identity provider capabilities, enabling new scenarios without disrupting the existing functionalities or your user’s experience. Furthermore, we will do all this without requiring any special security knowledge. The code we will demonstrate is not production ready, of course; however it should be enough for giving you idea of the general application’s structure.

Let’s assume that you are running a website which manages authentication via the mechanisms offered by ASP.NET Membership: the user store is based on SqlMembershipProvider, the credential gathering is implemented via forms authentication plus Login web control, roles and profile information are managed via the usual ASP.NET classes.

Let’s also assume that you have a business partner, running a website as well, which would like to be able to offer special conditions to your users: recognize them as your users, personalize the experience or handle authorization according to user information you keep in your profiles or roles, perhaps even achieve single sign on between your site and theirs. In other words, your business partner would like to use your website as an Identity Provider (IP). Traditionally, the trivial solutions to the problem (like duplicating credentials stores and keeping them synchronized) would require so much work that it would seldom make business sense: however claims based identity and the Windows Identity Foundation Framework lower the bar, making the above significantly easier to implement and maintain.

The Windows Identity Foundation Framework solution can be extremely simple: we just publish an extra page in our website, whose sole purpose is offering an entry point to our application when a user of ours wants to sign in a third party partner website. Such a page, which in the identity jargon takes the name of passive Security Token Service (or passive STS), will understand requests presented via standard protocol (in our exercise it will be WS-Federation, but the principle holds for other protocols as well) and will return the requested values using the same conventions. The use of standards not only guarantees that the third party website will be free to leverage whatever technology or platform uses the same standard, but also makes possible the use of specific tooling for automating many of those processes and hiding away the details of the specific implementation.

This hands-on lab will help you to apply the solution described above, by enhancing an existing APS.NET website with a simple STS and by configuring another website to take advantage of that STS.

Objectives

In this Hands-On Lab, you will learn how to:

Enhance an ASP.NET website with membership provider with identity provider capabilities

Configure an ASP.NET website to accept and authorize users from an external identity provider

System Requirements

You must have the following items to complete this lab:

Microsoft® Windows® Vista SP2 (32-bits or 64-bits) , Microsoft® Windows Server 2008 R2|SP2 (32-bit or 64-bit), Microsoft® Windows® 7 RTM (32-bits or 64-bits)

Microsoft® Internet Information Services (IIS) 7.0

Microsoft® .NET Framework 4.0

Microsoft® Visual Studio 2010

Microsoft® SQL Express 2008

Microsoft® Windows Identity Foundation Runtime

Microsoft® Windows Identity Foundation SDK

Setup

You must perform the following steps to prepare your computer for this lab.

1. Open a Windows Explorer window and browse to the lab’s Source\Setup folder.

2. Double-click the Dependencies.dep file in this folder to launch the Dependency Checker tool and install any missing prerequisites. This will also install some code snippets that will be used across the lab and the localhost certificate used in the second exercise by the local STS.

Note: This process may require elevation. The .dep extension is associated with the Dependency Checker tool during its installation. For additional information about the setup procedure and how to install the Dependency Checker tool, refer to the Setup.docx document in the Assets folder of the training kit.

3. Once closed the code snippets installer, the setup script will proceed with the certificates installation. Press Y if you want to continue with the required certificates installation.

Figure 1Installing the localhost certificate

Note: If you are running Windows 7 or Windows 2008 R2 you might not see this window.

4. When finished press any key to close the setup console.

Note: In addition to the setup script inside the %YourInstallationFolder%\Labs\MembershipAndFederation\Source\Setup folder, there is a Cleanup.cmd file you can use to uninstall all the code snippets installed by the SetupLab.cmd script.

Exercises

The following exercise makes up this Hands-On Lab:

1. Enhance an ASP.NET Membership Website with Identity Provider Capabilities and Use it from a Third Party Website

Note: Each exercise is accompanied by a starting solution. These solutions are missing some code sections that are completed through each exercise and therefore will not work if running them directly.

Inside each exercise you will also find an end folder where you find the resulting solution you should obtain after completing the exercises. You can use this solution as a guide if you need additional help working through the exercises.

Estimated time to complete this lab: 25 minutes.

Exercise 1: Enhance an ASP.NET Membership Website with Identity Provider Capabilities and Use it from a Third Party Website

In this exercise you will enhance an existing ASP.NET website which uses the membership provider with a passive STS page so it can work as an identity provider for other websites. Then, you will configure a second website to take advantage of it (or, using the common security terminology, federate with it).

Figure 2The general flow of the exercise’s solution

Task 1 - Preparing the Solutions

In this task you will take an existing website and configure it for using a pre-populated membership store file (ASPNETDB.mdf). In practical terms, this means giving write permissions to NETWORK SERVICE

(or IIS_IUSRS for Windows 7 and Windows Server 2008 R2) for the App_Data folder in order to allow IIS to read and write the ASPNETDB.mdf database.

1. Open Microsoft Visual Studio 2010 with administrator privileges. From Start | All Programs | Microsoft Visual Studio 2010, right click on Microsoft Visual Studio 2010 and choose Run as administrator.

2. Open the MembershipSite.sln solution file located in the %YourInstallationFolder%\Labs\MembershipAndFederation\Source\Ex1-EnhancingWithFederation\Begin folder.

3. Open a Windows Explorer instance and browse to the folder %YourInstallationFolder%\Labs\MembershipAndFederation\Source\Ex1-EnhancingWithFederation\Begin\MembershipSite.

4. Assign Write permission to NETWORK SERVICE (or IIS_IUSRS for Windows 7 and Windows Server 2008 R2) user for the App_Data folder of the Begin solution. To do this, right-click the App_Data folder, select Properties, go to the Security tab and click Edit. On the Permissions for App_Data select the "NETWORK SERVICE" user and check the Write permission. Click OK on each dialog.

Figure 3Assigning NETWORK SERVICE write permissions for App_Data

Note: If you want to run the End solution, follow the same steps in the %YourInstallationFolder%\Labs\MembershipAndFederation\Source\Ex1-EnhancingWithFederation\End\MembershipSite folder.

Task 2 - Inspecting the Initial Solution

1. Go back to the solution in Visual Studio.

2. Press F5 to run the Web site and accept to enable debugging in the Web site.

3. When redirected to the login page enter the username John and the password p@ssw0rd

Figure 4Log in page

4. Click Log In button.

Figure 5Default page showing a welcome message for the authenticated user

5. Close the browser.

Note: You can continue inspecting Web.config file. The web site is configured as any usual ASP.NET Web site to use Forms authentication method with the SQL membership provider. In the following task you will modify this website adding a passive STS page which will reuse the same membership mechanism.

Task 3 - Creating the Passive STS Page

1. On the Solution Explorer, right-click the project (https://localhost/MembershipSiteEx01) and select Add New Item.

2. Add a new Web Form using the name PassiveSTS.aspx and click Add.

3. Add a reference to the Microsoft.IdentityModel.dll assembly to the partner Web site. To do this, right-click on the https://localhost/MembershipSiteEx01 project, select Add Reference and add the Microsoft.IdentityModel component in the .NET tab.

Note: If you did not find the Microsoft.IdentityModel.dll assembly on the Add Reference dialog, you can add the reference including the following line in the configuration/system.web/compilation/assemblies section of the Web.config file:

<add assembly="Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />

4. Open the PassiveSTS.aspx.cs page.

5. In the PassiveSTS class, replace the existing code with the following:

(Code Snippet - Membership And Federation Lab - Ex 1 PassiveSTS Class)

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.Protocols.WSFederation;using Microsoft.IdentityModel.Web;using Microsoft.IdentityModel.SecurityTokenService;using System.Globalization;

public partial class PassiveSTS : System.Web.UI.Page{ protected void Page_Load(object sender, EventArgs e) {

}

protected void Page_PreRender(object sender, EventArgs e) { string action = Request.QueryString[WSFederationConstants.Parameters.Action];

try { if (action == WSFederationConstants.Actions.SignIn) { // Process signin request. SignInRequestMessage requestMessage = (SignInRequestMessage)WSFederationMessage.CreateFromUri(Request.Url); if (User != null && User.Identity != null && User.Identity.IsAuthenticated) { SecurityTokenService sts = new MembershipSTS(MembershipSTSConfiguration.Current); SignInResponseMessage responseMessage = FederatedPassiveSecurityTokenServiceOperations.ProcessSignInRequest(requestMessage, User, sts);

FederatedPassiveSecurityTokenServiceOperations.ProcessSignInResponse(responseMessage, Response); } else { throw new UnauthorizedAccessException(); } } else if (action == WSFederationConstants.Actions.SignOut) { // Process signout request. SignOutRequestMessage requestMessage = (SignOutRequestMessage)WSFederationMessage.CreateFromUri(Request.Url); FederatedPassiveSecurityTokenServiceOperations.ProcessSignOutRequest(requestMessage, User, requestMessage.Reply, Response); } else { throw new InvalidOperationException( String.Format(CultureInfo.InvariantCulture, "The action '{0}' (Request.QueryString['{1}']) is unexpected. Expected actions are: '{2}' or '{3}'.", String.IsNullOrEmpty(action) ? "<EMPTY>" : action, WSFederationConstants.Parameters.Action, WSFederationConstants.Actions.SignIn, WSFederationConstants.Actions.SignOut)); } } catch (Exception exception) { throw new Exception("An unexpected error occurred when processing the request. See inner exception for details.", exception); } }}

Note: This code is the same code created by the ASP.NET Security Token Service Web Site Visual Studio template. It provides the basic functionality of a passive token issuer that supports sign-in and sign-out. The solution will not compile right now, but in the following steps you will add a couple of assets that will make it work.

6. Open a windows explorer window and browse to %YourInstallationFolder%\Labs\MembershipAndFederation\Source\Assets.

7. Copy the App_Code and FederationMetadata folders and its content to the Web site folder (right-click the project https://localhost/MembershipSiteEx01/ and select Open Folder in Windows Explorer, then paste the files in the project folder).

8. Switch back to Visual Studio and click Refresh button on the Solution Explorer window.

Figure 6App_Code and FederationMetadata folders added

Note: The code you just added is a simplified version of the code generated by the Windows Identity Foundation Visual Studio templates. The STS will issue claims with the user name and the roles he has. For further understanding you can inspect the files just added and take a look at the GetOutputClaimsIdentity method in the MembershipSTS class. This is the method that we can use for customizing the identity information in the token that we will send to the third party website.

Task 4 - Creating the Partner Web Site

1. On Visual Studio go to File | Add | New Web Site.

2. On the Add New Web Site dialog select ASP.Net Empty Web Site project type, choose HTTP for the location and make sure language is set to Visual C#, and then provide the following name for the web site: https://localhost/MembershipSitePartnerEx01/ and click OK.

3. Add a reference to the Microsoft.IdentityModel.dll assembly to the partner Web site. To do this, right-click on the https://localhost/MembershipSitePartnerEx01/ project, select Add Reference and add the Microsoft.IdentityModel component in the .NET tab.

Note: If you did not find the Microsoft.IdentityModel.dll assembly on the Add Reference dialog, you can add the reference including the following line in the configuration/system.web/compilation/assemblies section of the Web.config file:

<add assembly="Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />

4. Add a new Web Form and use the name Default.aspx.

5. Open the Default.aspx page to add a FederatedPassiveSignInStatus control and a welcome message and set the body background color to #AFC1CE to differentiate the partner site from the membership site.

ASPX

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="Default.aspx.cs" Inherits="_Default" %><%@ Register assembly="Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" namespace="Microsoft.IdentityModel.Web.Controls" tagprefix="idfx" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head runat="server"> <title>Membership and Federation - Exercise 1</title></head><body style="background:#AFC1CE"> <form id="form1" runat="server"> <div> <h1>Welcome to your partner site</h1> <idfx:FederatedPassiveSignInStatus ID="SignInStatus1" runat="server" /> </div> </form></body></html>

6. On the Solution Explorer, right-click the https://localhost/MembershipSitePartnerEx01/ project and select Add STS reference.

Figure 7Add STS reference option

7. When the Federation Utility window shows up perform the following tasks for each step in the wizard.

a. On the Welcome page click Next to continue using the pre-populated fields.

Figure 8Welcome page

b. On the STS options page, select the third option button ("Use an existing STS"), set the STS metadata location to https://localhost/MembershipSiteEx01/FederationMetadata/2007-06/FederationMetadata.xml and click Next.

Figure 9Selecting a STS option

c. If the following warning message appears saying that there is a mismatch between the DNS name of the machine and the certificate subject name in the federation metadata press Yes.

Figure 10Warning message because of certificate and DNS name mismatch on the development environment

d. If you get a STS signing certificate chain validation error, select Disable certificate chain validation and press Next. If not, continue in the following step.

e. Select the Enable encryption option and then select the Select an existing certificate from store option.

Figure 11Using encryption with localhost certificate

f. Click Select Certificate and select the certificate for localhost.

Figure 12Selecting the certificate

g. Click Next.

h. In the Offered Claims page, click Next.

Figure 13Offered claims window

i. On the Summary page, review the changes and click Finish.

Figure 14Summary

8. In the web.config file, add the following line inside the system.webServer section.

XML

<validation validateIntegratedModeConfiguration="false"/>

Task 5 - Validating the STS Issues Tokens to a Specific Relying Party

To add additional security to the STS, you can limit the issuance of tokens to specific relying parties only. In this task, you will configure the STS to issue tokens for the partner site only.

1. Open the MembershipSTS.cs file from the https://localhost/MembershipSiteEx01/ project inside the App_Code folder.

2. Update the GetScope method to validate the AppliesTo property and throw an exception is the URI is not from the partner site. To do this, update the GetScope method as follows.

(Code Snippet - Membership And Federation Lab - Ex 1 AppliesTo Validation)

C#

protected override Scope GetScope(IClaimsPrincipal principal, RequestSecurityToken request){ Uri rpUri = new Uri("https://localhost/MembershipSitePartnerEx01/");

if (!request.AppliesTo.Uri.Equals(rpUri)) { throw new InvalidRequestException(String.Format("The AppliesTo address {0} is not valid.", request.AppliesTo.Uri.AbsoluteUri)); }

Scope scope = new Scope(request, SecurityTokenServiceConfiguration.SigningCredentials); scope.EncryptingCredentials = new X509EncryptingCredentials(CertificateUtil.GetCertificate(StoreName.My, StoreLocation.LocalMachine, "CN=localhost")); scope.ReplyToAddress = scope.AppliesToAddress + "/Default.aspx"; return scope;}

Note: The AppliesTo will return the URL for the Relying Party that is requesting for tokens to the STS. In the previous code you are checking that the Relying Party that is requesting the token is a valid one.

Task 6 - Customizing Authorization with Different Roles

1. Add a new Web Forms to the https://localhost/MembershipSitePartnerEx01 project and name it SecretPage.aspx.

2. Add the following message to the SecretPage.aspx.

ASPX

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml"><head runat="server"> <title></title></head><body style="background:#AFC1CE"> <form id="form1" runat="server"> <div>

<p>This is a secret page; you can get here only if you are a manager.</p> </div> </form></body></html>

3. Open the web.config file from the https://localhost/MembershipSitePartnerEx01 project.

4. Add the following settings under the configuration element to enable access to SecretPage.aspx only for users in Manager role.

(Code Snippet - Membership And Federation Lab - Ex 1 SecretPage.aspx Authorization Settings)

XML

<configuration> ... </configSections> <location path="SecretPage.aspx"> <system.web> <authorization> <allow roles="Manager"/> <deny users="*"/> </authorization> </system.web> </location> <location path="FederationMetadata"> ...</configuration>

Note: This is plain old ASP.NET configuration. It will work because the token contains role claims (http://schemas.microsoft.com/ws/2008/06/identity/claims/role) and the ClaimsPrincipal implements IsInRole by checking the list of claims where claim type is the one defined above.

5. Build the solution, to do this press CTRL+SHIFT+B.

Exercise 1: Verification

1. Open a browser and navigate to https://localhost/MembershipSitePartnerEx01/.

Figure 15Log in page from MembershipSiteEx01

Note: You were redirected to the Log in page from MembershipSiteEx01 since MembershipSitePartnerEx01 is federating the authentication to MembershipSiteEx01. Once you get logged in you will be redirected back to the MembershipSitePartnerEx01.

Note: If you want to run the End solution, assign Write permission to NETWORK SERVICE user (or IIS_IUSRS for Windows 7 and Windows Server 2008 R2) in the App_Data folder of the End solution.

Note: If your SQL Express instance name is other than SQLEXPRESS, add the following configuration to the web.config under the Web Site https://localhost/MembershipSiteEx01 (show in bold):

<connectionStrings>

<remove name="LocalSqlServer"/>

<add name="LocalSqlServer" connectionString="data source=.\<YOURINSTANCESQLEXPRESSNAME>;Integrated Security=SSPI;AttachDBFilename=|DataDirectory|aspnetdb.mdf;User Instance=true" providerName="System.Data.SqlClient"/>

</connectionStrings>

2. Enter valid credentials (john/p@ssw0rd) and click Log In.

Figure 16Logged in MembershipSitePartnerEx01

Note: Notice that you logged in MembershipSiteEx01 and now you are authenticated in the MembershipSitePartnerEx01 also.

3. Browse to https://localhost/MembershipSitePartnerEx01/SecretPage.aspx.

Figure 17Access Denied for user John

Note: The current user John does not have the required role for accessing the SecretPage.aspx

4. Go back (press backspace key).

5. Click on Sign out.

6. Log in using the Paul's credentials. Enter the username paul and the password p@ssw0rd

7. Now browse to https://localhost/MembershipSitePartnerEx01/SecretPage.aspx.

Figure 18Access granted for user Paul

8. Go back (press backspace key).

9. Click Sign out.

10. Navigate to https://localhost/MembershipSiteEx01/, enter valid credentials (john/p@ssw0rd) and click Log In.

Figure 19Logged in MembershipSiteEx01

11. Now browse to https://localhost/MembershipSitePartnerEx01/

Figure 20Logged in MembershipSitePartnerEx01 without Authenticating Again (Single Sign On)

Note: You did not have to enter your credentials again since the web site is federating against the same STS which you already have a cookie for.

The STS will issue tokens only when the AppliesTo element of the RequestSecurityToken is equal to https://localhost/MembershipSitePartnerEx01. As an extra exercise you can try creating another relying party website and configure it to federate against this STS. It will throw an exception.

12. Close the Web browser.

Summary

In this hands-on lab we explored one way of taking advantage of the advanced capabilities of Windows Identity Foundation Framework in a very common scenario, collaboration between partner websites, without having to become security experts. There are many other ways in which claims-based identity and Windows Identity Foundation Framework could be used for enhancing websites: if you want to know more, you can go though the other hands-on labs in the Identity Developer Training Kit, or refer to the Windows Identity Foundation Framework SDK samples.