Passport Authentication | Security for Microsoft Visual Basic .NET

The remainder of this chapter discusses how to create a Web application that authenticates users with the single sign-in (SSI) capabilities of Microsoft .NET Passport. Because Passport authentication is a fully featured, production-quality authentication mechanism, setting it up requires more effort than is required for simple Forms authentication and Windows authentication examples. This section covers enough to get you up and running with a development environment that uses Microsoft .NET Passport SSI authentication. This section doesn’t discuss the details of moving the site into production. The exercises use version 2.5 of Microsoft .NET Passport, which is the most current version at the time of this writing.

What is Microsoft .NET Passport? .NET Passport is a centralized sign-in service. Users set up their .NET Passport once, and then they use it to automatically sign in to any site that supports Passport authentication. From the user’s point of view, .NET Passport simplifies the Web because the user only has one username and password to remember for access to any Passport-authenticated site. From the Web-site developer’s point of view, .NET Passport simplifies authentication because developers don’t have to create their own authentication mechanism or user-management facilities. If you use Hotmail, you already have a .NET Passport account, and you probably know that your .NET Passport login is good at other Passport-authenticated sites as well, such as MSN Messenger, MSN 8.0, and various shopping sites.

.NET Passport is often confused with MSN Messenger. Messenger uses .NET Passport for authentication, but Messenger is not Microsoft .NET Passport itself, and signing into Messenger does not automatically sign you into every Passport- enabled Web site. Each Passport-enabled application manages its own authentication state. You can be logged on to a Passport-enabled Web site without being logged on to MSN Messenger. You can log on to Messenger with one set of .NET Passport credentials and simultaneously log on to http://www.msn.com using a different set of .NET Passport credentials.

How does Passport authentication work? When a user of your Web application attempts to access a Web Form that requires authentication, ASP.NET automatically redirects the user to the Microsoft .NET Passport site to sign in. During the SSI process, the user’s browser communicates directly with the Microsoft .NET Passport service using encrypted cookies. After a user signs in, the .NET Passport service redirects the user’s browser back to the calling site, and the application then has access to the user’s identity through the ASP.NET PassportIdentity object. Microsoft .NET Passport authentication works with all browsers. Microsoft .NET Passport also offers other services—such as Kids passport—however, this section will concentrate on the basics: implementing an SSI for using the Passport service. Because you are about to become a Microsoft .NET Passport developer, we will let you in on a secret: Passport actually has two completely separate environments—a live environment and a preproduction environment. The live environment is what 99% of the population uses to log into Messenger, Hotmail, MSN, and other applications. The preproduction environment is a replica of the live production environment, but it’s intended solely for application development and testing. The preproduction environment maintains its own separate set of passports, enabling you to develop and test an application without any interference with the live .NET Passport environment.

To implement Passport authentication, you will do five things:

Install the Microsoft .NET Passport Software Development Kit.
Set up the client. Sign up for two .NET Passports (a live .NET Passport and a preproduction .NET Passport), and learn how to switch the client between live and preproduction modes. You will use the live Passport for signing into the .NET Services manager Web site, and you’ll use the preproduction Passport for testing the Web site.
Register a Web application with the .NET Services manager Web site.
Configure your server with the registration information obtained from the .NET Services manager Web site.

Create a Web application that uses Passport for authentication.

Note

The following sections refer to resources on live Web sites. Because you’ll read this chapter at least several months after it was written, some of the page layouts and links might have changed from what is presented here. For this reason, we explain to a greater degree the concepts associated with each task along with how to use the current versions of the Web sites.

Install the Passport SDK

The .NET Framework includes classes for working with .NET Passport, but these are merely wrappers that won’t do anything until you install the Microsoft .NET Passport SDK. The SDK contains the dynamic-link libraries (DLLs) that provide essential services such as the Passport Manager, Passport Crypt, Passport LookupTable, and Passport Factory objects. It also contains documentation and a site-administration utility. The SDK is available as a free download from msdn.microsoft.com. Look for the article “Microsoft .NET Passport Software Development Kit” at the address http://msdn.microsoft.com/downloads/sample.asp?url=/msdn-files/027/001/885/msdncompositedoc.xml . You should download and install both the Windows SDK v2.5 bits and the Windows SDK v2.5 docs.

Set up the client

In this exercise, you will learn how to switch your computer from the live .NET Passport environment to the preproduction environment and back to the live environment. While in the preproduction environment, your computer will only be able to sign into Web sites that are also in the preproduction environment. You will also sign up for a .NET Passport (if you don’t have one) and for a second, preproduction Passport.

If you don’t already have a passport, go to the Web site http://www.passport.net and click the link Register For Your Free .NET Passport Today to obtain a passport. This is the .NET Passport you’ll use for signing in to Passport-enabled Web sites and for administering your application. In this chapter, we’ll refer to this .NET Passport as the live passport.

Now you will switch your computer from the live passport environment to the preproduction passport environment.
Start the RegEdit utility. You do this by choosing Run from the Start menu, typing RegEdit.exe, and pressing Enter.
In RegEdit, back up the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\ Internet Settings\Passport key by right-clicking the Passport key and choosing Export on the shortcut menu. Save the exported file with the name Live-Passport.reg.
In RegEdit, back up the HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\ Internet Settings\Passport\DAMap key by right-clicking the Passport key and choosing Export on the shortcut menu. Save the exported file with the name Live-DAMap.reg.
In RegEdit, delete the two keys you just backed up— HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\ Internet Settings\Passport and HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings \ Passport
\DAMap.
Download and run the following reg file to update your registry: http://www.passport.com/downloads/blaze-default.reg.

This adds two values, NexusHost and NexusObj, to the passport key. After deleting the Passport and DAMap keys and running this file, your computer is now configured to use the preproduction environment. While in the preproduction environment, you won’t be able to use your live passport to sign into Web sites. Instead, you will need to sign up for a preproduction passport.
Go to the Web site http://www.passport-ppe.net (the ppe stands for preproduction environment), and click the link Register For Your Free .NET Passport Today. In this chapter, we’ll refer to this .NET Passport as the preproduction passport. Interestingly, preproduction passports work only with Web sites that are also in preproduction, and live passports work only with Web sites that are using the live passport environment.
To move your computer back to the live environment, in RegEdit delete the key HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\ Internet Settings\Passport and run the files live-Passport.reg and live-DAMap.reg to restore your live environment settings.

You can switch from live to preproduction by deleting registry keys and running the appropriate registry file. Because editing the registry by hand is a laborious and error-prone task, and because the purpose of this book is to make security easier, we have included a program in the practice files named TogglePassportEnvironment, which toggles the computer between live and preproduction environments.

Register a new application with Microsoft .NET Passport

Before your Web application can use Passport authentication, you’ll need to register the application with the Microsoft .NET Passport service and obtain a Site ID. In this exercise, you’ll register a new application named PassAuth with the online passport service.

In Internet Explorer, navigate to the site https://www.netservicesmanager.com. This site is used for maintaining and registering new Passport Web applications with the .NET Passport service.
Sign in using your live passport.

Click on the link Create An Application In Our DEV/TEST Environment. Doing this starts an online wizard that collects information about the new application. Table 4-3 gives values to use for the required fields and provides notes about the meaning of each. The other optional fields are not included here.

Table 4-3: Values for Registering a New Application with Passport
Field Name	Value	Notes
Application Name	PassAuth	This is the name of the application. You should use the project name.
Service	.NET Passport Single Sign-in	This refers to the check box on the services page you should check to select the SSI service for your application.
Web Site Title	PassAuth	This is the title of the application. You should use the application name.
Domain Name	localhost	This is the top-level domain name of your site. For example, microsoft.com. Because you are developing and testing the site on a single machine, you should use localhost.
Default Return URL	http://localhost/PassAuth /Default.aspx	This is the default page the user will be directed to after signing in, assuming another URL is not specified.
Privacy Policy URL	http://www.passport.com/consumer/privacypolicy.asp	This is the location of your site’s security policy.
Cobrand Image URL	http://localhost/PassAuth /logo.bmp	This is the location of your site’s logo, which will be used in the login prompt page. This logo should be 468x80 pixels. Passport authentication will still work if this bitmap is missing.
Cobrand Image2 URL	http://localhost/PassAuth /logo.bmp	This is the location of your site’s logo to be used in user credential boxes. This logo should be 102x80 pixels and a gif. Passport authentication will still work if this gif is missing.
Cobrand Instruction Text	Sign in to PassAuth	This is the instruction text for the sign-in page.
Expire Cookie URL	http://localhost/PassAuth /ExpireCookie.aspx	This is the URL of the page that will delete all the cookies set by .NET Passport for your site.

After registering your application, the .NET Services Manager site will display the Site ID of the application. Write it down; you will use this later. The Site ID is a number—for example, the Site ID for the application we created when writing this book is 33729.
Click on the Return To Manage My Applications link, choose PassAuth in the combo box, and click Select to show the details of the site.
Click the Download a key link, and follow the instructions to download to your machine the encryption key for this site. This key is used to encrypt information that is passed between your Web site and the passport servers.
To install the key, open a command prompt and run two commands:
```
<path>\Partner<keynumber>.exe /addkey
```
and then
```
<path>\Partner<keynumber>.exe /makecurrent /t 0
```
where <path> is the path to the file, and <keynumber> is the unique number of the key. For example, if you download the key to the c:\temp directory and the keynumber is 33729_1, the two commands would be as follows:
```
c:\temp\Partner33729_1.exe /addkey
c:\temp\Partner33729_1.exe /makecurrent /t 0
```
Your computer is now configured to encrypt and decrypt passport information with this site.

Configure your server

In this exercise, you’ll configure your server with the Passport Administration Utility.

Run the Passport Administration Utility that was installed with the Passport SDK. You can access this by stepping through the following menu items: Start Menu|All Programs|Microsoft Passport|Passport Administration Utility.
In the Passport Administration Utility, register a new Web site named PassAuth. You can leave most of the fields blank, but you must enter the SiteID you wrote down in Step 5. After finishing, click Commit Changes to save this information. The Passport Administration utility should look similar to the following illustration:

Create a Passport-enabled Web application

In this exercise, you’ll create a new Web application that will authenticate users via .NET Passport.

Start Visual Basic .NET, and create a new ASP.NET Web application named PassAuth.
Open the Web.Config file, and change the authentication section to
```
<authentication mode="Passport" />
```
Change the name of the default Web Form from WebForm1.aspx to Default.aspx.
To the Default.aspx Web Form, add four text boxes and name them txtEmail, txtMemberID, txtMemberName, and txtSiteID. These four text boxes will be used to show the Site ID of the application, the signed-in user’s e-mail address, name, and unique member identifier. Because the site is in preproduction mode, most of these will be dummy values.

Double-click the background of the form to open the Page_Load event handler. Enter the following text:

Private Sub Page_Load(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles MyBase.Load
 Dim pass As System.Web.Security.PassportIdentity
 pass = Page.User.Identity
 Dim strRedirectURL, strLogoTag As String
 ’URL that a successful sign in will redirect to
 strRedirectURL = "http://localhost/PassAuth/Default.aspx"
 ’Get the HTML for the sign in/sign out button
 strLogoTag = pass.LogoTag2(strRedirectURL, 14400, False, _
 Nothing, 1033, False, Nothing, 0, False)
 ’Draw the button on the top left of the page
 Response.Write(strLogoTag)
 If pass.IsAuthenticated Then
 ’Member’s Email address
 Me.txtEmail.Text = pass("PreferredEmail")
 ’MemberID
 Me.txtMemberID.Text = pass("MemberIDHigh") & pass("MemberIDLow")
 ’Member’s name - warning this is deprecated 
 Me.txtMemberName.Text = pass("MemberName")
 ’Passport Site ID of this site
 Me.txtSideID.Text = pass.GetCurrentConfig("SiteID")
 End If
End Sub

Add a second Web Form to the project named ExpireCookie.aspx.

Double-click the background of the form to open the Page_Load event handler. Enter the following text:

Private Sub Page_Load(ByVal sender As System.Object, _
 ByVal e As System.EventArgs) Handles MyBase.Load
 Dim pass As System.Web.Security.PassportIdentity
 pass = Page.User.Identity
 If pass.IsAuthenticated = True Then
 ’Insert cookie cleanup here...
 ’
 ’Return a GIF to passport to indicate that signout
 ’was successful
 pass.SignOut("Signout.gif")
End If
End Sub

Add a gif file to the project directory, and name it signout.gif. The ExpireCookie.aspx page uses this gif as a parameter in the SignOut method to indicate a successful sign out.
Before running the application, ensure the computer is in preproduction mode by using the TogglePassportEnvironment application.
Press F5 to run the application. Because initially you are not signed in, you will see a page similar to the following illustration. (As you’ll see in the Finished example, we added a few more controls to make the page pretty.)
Click the Sign In button to sign in to passport. The passport sign-in dialog box will look similar to the following illustration. Notice the dialog box is customized with your site’s co-brand instruction text and co-brand graphic.
Enter your preproduction passport username and password. After signing in, the Default.aspx Web form will look similar to the following illustration. Congratulations! You have just written your first Passport-enabled application.

This application shows the basics of Passport authentication, which allows you to verify the identity of a user who signs into your Web site. This application used a soft sign-in, which means that the user is not forced to sign in. The page offers some information without signing in, but it offers more or different functionality after signing in. Passport does not have a built-in authorization mechanism or a way to centrally store cookies such as the user’s credit card information. A common approach is for applications to store this information in a database, using the .NET Passport MemberID or HexPUID fields as the primary key.