his first installment of a two-part series on Microsoft Passport in ASP.NET applications discusses Passport’s basic authentication mechanism and demonstrates the use of related .NET classes. It describes the design and implementation of Passport-enabled Web applications and how such applications communicate with client browsers and Passport servers.

Beginning with a general description of how Microsoft Passport acts as an authentication service, it then describes the sequence of events that occurs when a user (normally a browser client) tries to access a Passport-enabled application. The following section demonstrates the necessary setup steps, and the final section explains how to use ASP.NET classes that wrap the authentication-related functionality that the Passport server provides.

Microsoft Passport as an Authentication Service
E-commerce applications on the Internet use electronic means to identify people trying to reach their enterprise resources. For example, when you create a new Yahoo e-mail account, you enter some personal information along with a user name and a password. The name/password pair becomes your identification when you later check your e-mail messages on the site. This simple authentication mechanism is also applicable to e-commerce applications. The login and password pairs are used to identify site users.

The user-authentication mechanisms that e-commerce applications normally have to implement require the following features:

1. A graphical user interface (GUI) for sign-up and login
2. A database of user information (at least user names and passwords)
3. Authentication logic at the Web server
4. Log-out functionality, such as deleting (or destroying) server-side session objects

Microsoft .NET Passport, in its most basic form, provides all four of these features wrapped inside an easy-to-use programmatic interface. Passport provides a simple architecture, in which a single .NET Passport class named System.Web.Security.PassportIdentity wraps all authentication functionality. A Passport-enabled Web application developer need only instantiate the PassportIdentity class and use its methods to perform the complete authentication process.

This means Passport-enabled e-commerce application developers can rely on Passport to manage all the authentication features required by their e-commerce sites. In effect, Passport is a reusable authentication component, pluggable directly into an ASP.NET-based e-commerce application, which makes it very suitable for rapid application development.

Single Sign-on
Single sign-on (SSO) is another important benefit of Passport. Microsoft hosts its Passport service on its own servers and allows the use of all Passport-enabled accounts (e.g., all Hotmail and MSN.com accounts) to be authenticated on all Passport-enabled Web applications. This means users with Passport-enabled accounts need to remember only one login password pair to access all partner sites. So Passport not only allows rapid e-commerce application development, but it provides ease for users as well.

Author’s Note: Microsoft Passport is not the only SSO solution available. Almost all major e-commerce vendors like Oracle and IBM are offering SSO solutions. A major contender for Passport is the Liberty Alliance (see Related Resources for details).

On the other hand, if you host your SSO on your own server, you can offer it only to your own user base?not all Hotmail and MSN users. You’ll normally find this type of SSO in enterprise integration applications, where the application is meant only for users who belong to a particular trusted domain (e.g., employees of a company).

Microsoft currently sells Passport as a hosted service, like an application service provider (ASP). Passport is not available as a software product or a component you can host on your Web servers. The disadvantage of this strategy is if you want to authenticate your own user base on a Passport-enabled site, you have to implement your own authentication mechanism in addition to Passport.

This disadvantage makes Passport a generally unsuitable authentication solution for enterprise application integration (EAI) projects. In most EAI projects, customers don’t want their users authenticated on a third-party server, because third-party authentication unnecessarily exposes their business information. For such applications, SSO solutions from other vendors like Oracle or IBM are better, as they are available as software components that customers can host on their Web servers.

However, B2C e-commerce applications can take advantage of the Hotmail and MSN user base with Passport.

Passport Information Exchange
Figure 1 shows the exchange of information that takes place when a browser-based user accesses a Passport-enabled site. Notice that three participants are involved in the conversation:

1. The user is a client browser.
2. The Passport-enabled application is a Web site or an e-commerce application that uses Passport for authentication purposes.
3. The Passport server is the Passport-based authentication service hosted by Microsoft on its servers.

Figure 1: Passport Information Exchange When User Accesses Site

The following is an explanation of each step shown in Figure 1:

1. A user accesses the Passport-enabled site using a browser.
2. The Passport-enabled site detects that the HTTP request is coming from a user who is not yet authenticated. So it includes a Passport Sign-in button in its response to the user. (Figure 2 shows a simple Web page that includes a Passport sign-in button.)
3. The user presses the sign-in button, which generates an authentication request to the Passport-enabled site. (For the sake of simplicity, Figure 1 shows the request going straight to the Passport server. In actuality, the Passport-enabled application redirects the request to the Passport server.)
4. The Passport server, on receipt of the sign-in request, sends the user a Web page that includes the user name and password text-entry fields. (Figure 3 shows a simple page including these two text fields.)
5. The user enters a login name and a password into the data-entry fields and presses the sign-in button. This generates an authentication request to the Passport server, which carries the user name and password to the Passport server.
6. The Passport server, on receipt of the authentication request, checks the user name and password for authentication.
7. If the user is successfully authenticated, he or she is redirected to the Passport-enabled site.
8. The Passport-enabled application, on receipt of an authenticated request, grants the user access to the requested page.

Figure 2: Web Page with a Passport Sign-in Button

Figure 3: Web Page with User Name and Password Text Fields

This simple eight-step procedure depicts how Passport-enabled applications coordinate with Passport servers and client browsers to perform user authentication. The following section explains the setup process a developer needs to follow before creating a Passport-enabled application.

Setting Up a Development Machine for Passport-enabled Applications
This section demonstrates the steps required to set up a development machine for a Passport-enabled site. Although very easy, this setup is a lengthy process that involves quite a lot of steps. The following sections describe each step.

Step 1. Create a Passport-enabled User Account
Create a Hotmail account at www.hotmail.com. If you already have an e-mail account at Hotmail or MSN, you can skip Step 1 because these accounts are Passport-enabled by default.

Step 2. Register Your Application with the Passport Server
To register your application with the Passport server, go to http://www.netservicesmanager.com. You will see a page labeled .NET Services Manager (as shown in Figure 4). Press the sign-in button at the upper right corner of the screen. You will receive a .NET Passport Sign-In page (see Figure 5). Enter the e-mail account and password you got from Step 1 and press the sign-in button. The next screen asks for some personal information (first name, last name, address, etc.). Entering the required information will take you to a screen that contains a “Create an application” link (as shown in Figure 6). This link returns the “Create application” screen, which contains a text field with a label named “Application Name.” Enter the name of your application in this text field and press the “Continue” button.

Figure 4: The Page Labeled .NET Services Manager

Figure 5: .NET Passport Sign-In Page

Figure 6: Screen with a “Create an application” Link

The “Select Services” screen shown in Figure 7 is the next screen you’ll see. It presents three options: Kids Passport, .NET Passport Single Sign-in, and .NET Passport Express Purchase. Select the .NET Passport Single Sign-In option and press the Continue button.

Figure 7: The “Select Services” Screen

Author’s Note: The Kids Passport service provides parental consent services for sites offering content that may not be appropriate for children under 13 years of age. The Express Purchase service shares user credit card and billing information with Passport-enabled sites.

Step 3. Enter All the Required Information About Your Site
You will now get a number of screens, one after the other, that gather information regarding the site you want to register with Microsoft Passport. Each screen contains several fields, some of which are mandatory (shown in bold on the screen) and others that are optional. Since each field offers explanatory text to help you enter data accordingly, I explain only the fields that are important for understanding how Passport-enabled applications operate:

Domain Name and Default Return URL Fields
You should enter the domain name of the Web application you are registering in the domain name field. For example, www.devx.com is a valid entry for the domain name field.

The Default Return URL field is the address of the ASP.NET page that will be displayed to the user after a successful sign-in. The top-level name of this URL should match the domain name field. For example, if the domain name field was www.devx.com then the default return URL should be something like http://www.devx.com/security.

During development, you may also test pre-production sites while they are being hosted on IIS on local machines. In such a case, use the name of a machine on your local network as the domain name. The default Return URL will also contain the name of the local machine. For example, if the name of the machine is bsiddiqui and the page that you want displayed on your local machine after successful sign-in is identified by the URL myPassportEnabledApplication/WebForm1.aspx, then you would use the following values for the domain name and return URL fields:

Co-branding Information
Microsoft allows Passport-enabled applications to give a customized look to the Passport Sign-In page through co-branding information. Co-branding information helps maintain the look and feel of your Passport-enabled application so it remains consistent during sign-in. Although co-branding information, which includes images and style sheets, is not mandatory requirement, it is recommended.

Expire Cookie URL
The ASP.NET page residing on this URL is invoked on logout. Its purpose is to delete any cookies written by Passport server in the Passport-enabled application domain during sign-in. Passport server, instead of deleting the cookies itself, lets the Passport-enabled application delete them and makes sure that deleting the cookies does not affect its business logic.

Step 4. Log Your Site ID
The registration process is now complete. You will get a congratulations screen (as shown in Figure 8) that provides you a site ID. Write this ID down; you will need it later. You can register as many applications as you want (with the same e-mail account you got in Step 1), and each successful registration results in a site ID.

Figure 8: A Congratulations Screen with Your Site ID

Step 5. Go to the “Manage My Applications” Page
The congratulations screen also contains a link named “Manage My Applications.” Click this link to reach the “Manage My Applications” page (as shown in Figure 9).

Figure 9: The “Manage My Applications” Page

Step 6. Select Your Registered Application
The drop-down list on this page contains all the applications that you registered using the same e-mail account. Select the application you just registered in Steps 1, 2, 3, and 4. You will get all the information related to the application, along with a number of links (as shown in Figure 10).

Figure 10: All the Information Related to Your Application

Step 7. Initiate the Key Download
Click the “Download a Key” link to start the key download procedure. Select the service, operating system, and the Web server. The code for this article was tested for the Passport service, Windows operating system, and the IIS Web server. After entering this information, press the select button.

Step 8. Download the Key to a Convenient Location
Next, you’ll see the key download screen, which contains a “Download Key” button. Pressing the button downloads and saves a key to your hard disk at the location of your choice. The key is downloaded in the form of an .exe file with the following name format:

Passport server uses this key for secure communication with the Passport-enabled application. Store it in a convenient location. You will need it shortly.

Step 9. Download and Install Passport SDK
To assist in rapid application development, Microsoft offers a class named “PassportIdentity” that wraps all the HTTP communication you will need to do with the Passport server. This leaves an easy-to-use interface for developing Passport-enabled applications.

Microsoft also produces a GUI to configure the communication with Passport server. All classes and GUIs are bundled as an SDK called Passport SDK. You will need this SDK before you can use Passport features in ASP.NET. Download Passport SDK, install it on your machine, and run the Passport manager administration utility.

Step 10. Complete the Passport Manager Administration Utility
Figure 11 shows the GUI of the Passport manager administration utility. You need only fill in the Site ID text field with the Site ID you got in Step 4. The rest of the fields are optional. You may have to change the value of the Language field, which is set of US English by default.

Figure 11: GUI of the Passport Manager Administration Utility

Step 11. Getting a Test Account
Up until now, you’ve used your .NET Passport-enabled e-mail account (Hotmail or MSDN) to register your application. However, to test pre-production Passport-enabled applications, you need a separate test account. You use this account only during development. Once you’ve paid Microsoft the fee for using the Passport service, you won’t need it.

The Passport server keeps the development accounts separate from production accounts. Pre-production sites cannot work with Passport-enabled accounts. So if you try to use a Hotmail account (or any other Passport-enabled account) to authenticate on a pre-production site, the authentication will fail. That’s why you need to get a test account.

The following steps register you for a .NET Passport-enabled test account:

1. Obtain an e-mail address other than Hotmail or MSN.com.
2. Visit the Microsoft Passport test account registration site (http://current-register.passporttest.net/). You will encounter a registration page that asks for an e-mail address, a password, and some personal information (see Figure 12). If you’re willing to share your personal information with the site(s) you will test using this account, you can check the boxes labeled “share my e-mail address” and “share my other registration information.” Microsoft administrates test accounts separately from the real Passport-enabled accounts.

Figure 12: Registration Page Asks for E-mail, Password, and Personal Information

Step 12. Install the Key You Downloaded in Step 8
Execute the Partner_32841_1.exe file with the “addkey” switch on the command prompt, as shown here:

Partner32841_1 /addkey

Step 13. Instruct the IIS to Use the Key
Once the key is installed, you need to tell your IIS to use this key. Execute the same Partner_32841_1.exe file with two switches, as shown here:

Partner32841_1.exe /makecurrent  /t 0

The “makecurrent” switch instructs IIS to start using this key after “t” seconds. So if the “t” switch value is 0, IIS starts using this key immediately.

Step 14. Create a New ASP.NET Project
You need to make a small change in the web.config file, which you will find among your project files. Open the web.config file and change the value of the “mode” attribute of the “authentication” element from “Windows” to “[Windows/Forms/Passport/None]”. This will allow your ASP.NET application to use Passport-based authentication in addition to other types of authentications.

Now that you have successfully configured your machine and the application that you want to build, you can start developing your first ASP.NET application.

Developing an ASP.NET Application with Passport Authentication
Using MS .NET Passport greatly simplifies the authentication process. You just need to instantiate a PassportIdentity object and then call its methods.

Listing 1 shows an ASP page that makes use of the PassportIdentity class. Notice the call to the PassportIdentity constructor, which does not take any argument and returns a PassportIdentity object:

Dim passportId As New System.Web.Security.PassportIdentity()

Once you have a PassportIdentity object, call its LogoTag2 method:

passportId.LogoTag2( Page.Request.Url.ToString(), _ 	14400, _	False, _	Nothing, _	1033, _	Page.Request.IsSecureConnection, _	Page.Request.ServerVariables("SERVER_NAME"), _	0, _	False)

Author’s Note: Older versions of Passport SDK (versions earlier than 1.4) contain a deprecated method named LogoTag, which serves the same purpose that LogoTag2 does. LogoTag follows a slightly different authentication sequence from LogogTag2, and older applications need to change the method name from LogoTag to LogoTag2 to work with later versions.

The LogoTag2 method automatically checks whether the user accessing the site has sent authentication information along with his or her request. If it finds the authentication information, it concludes that the user is already authenticated and produces the HTML code and the image for the Sign-out button. If the user is not authenticated, it produces the HTML code and the image for the sign-in button (as shown in Figure 2). Listing 2 provides the complete HTML code for the page shown in Figure 2.

When the user presses the sign-in button, it generates a sign-in request to the Passport server, which returns the page shown in Figure 3. (Listing 3 provides the HTML code for this page.) As you’ll recall, the page in Figure 3 contains two fields, one for the user name and the other for the password. The user enters the test account information that he or she created in Step 13 and presses the sign-in button, generating an authentication request to the Passport server. After authentication, the Passport server returns the user to the Passport-enabled site, which in this case is the same as the ASP.NET page shown in Listing 1.

This time, the Passportidentity.LogoTag2 method shows the Sign-out image?not the Sign-in image (see Figure 13). Know why? Because the Passport server, while redirecting the user to the Passport-enabled site, sent all the authentication information as parameter-value pairs along with the re-direction URL. The PassportIdentity.LogoTag2 method automatically detected the correct authentication information (as parameter-value pairs) and displayed the Sign-out image.

Figure 13: Passportidentity.LogoTag2 Method Shows Sign-out Image

The authentication process is now complete.

Interesting Properties of the PassportIdentity Class
All the properties of the PassportIdentity class are included in the code block within the “if passportId.isAuthenticated” statement (see Listing 1). This code block did not execute when the unauthenticated user visited your ASP.NET page for the first time. It executed only when the user was redirected to your ASP.NET page after a successful authentication.

You usually use these properties to fetch, store, or process information related to the user accessing your ASP.NET page. However, for the sake of demonstration, Figure 13 simply displays the information to the user. You would use the properties according to the business logic of your application.

Listing 4 is the HTML code that the Passport server will generate when your ASP.NET page is accessed after authentication. Compare Listing 4 with Listing 2 (the one that contains HTML code for the same ASP.NET page when accessed before authentication). The two listings are quite different from each other. The PassportIdentity class makes the difference.

Stay Tuned for SSO
In this article, you’ve learned how to use basic authentication features in MS Passport. You now understand the information exchange that occurs when a user accesses a Passport-enabled application. You can prepare a development machine for Passport applications and write code for a Passport-enabled ASP.NET page.

The second article in this series will demonstrate SSO across different ASP.NET applications. It also will explain the data format different parties use to communicate and discuss the use of keys, certificates, and tickets to carry information securely across the Internet. A detailed discussion of the logout procedure also will be discussed.