Setting Up .NET Passport in IIS 6.0

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1

Before setting up Microsoft .NET Passport authentication on your Web sites in a production environment, you are required to test IIS against .NET Passport preproduction servers. By working through this process, you confirm that your IIS server and the .NET Passport server are communicating correctly, your site(s) is registered with .NET Passport (which might involve signing forms and agreements), and your Web sites have the required site IDs. You must complete each process for every Web site you want to enable with .NET Passport authentication.

This topic includes the following information:

• .NET Passport Environments

• Testing and Preproduction (PREP)

• Mapping to Active Directory

• Configuring for Preproduction (PREP)

• Configuring for Production

• Passport Manager Administration Utility

With .NET Passport authentication on members of the Windows Server 2003 family, the default .NET Passport SecureLevel setting is 10. This means that new sites using .NET Passport authentication (and default settings) require an Secure Sockets Layer (SSL) server certificate. You can change the SecureLevel setting for a site by changing a registry value.

Procedures

To change the SecureLevel setting for the default Web site

• Enter a new value in the registry for the following key:

  HKEY_LOCAL_MACHINE\Software\Microsoft\Passport\SecureLevel

To change the SecureLevel setting for any Web site other than the default Web site

• Enter a new value in the registry for the following key:

  HKEY_LOCAL_MACHINE\Software\Microsoft\Passport\Sites\<Site Name>\SecureLevel

.NET Passport Environments

Setting up .NET Passport on your Web sites involves testing and configuring IIS against the following three .NET Passport environments:

• Default installation environment: By default, the Microsoft .NET Passport SDK and Internet Information Services (IIS) (with the Passport Manager object) are configured for testing. The test or default installation environment uses a site ID of 1 (one), and has a default encryption key instead of a private, site-specific key.

• Preproduction: The Preproduction (PREP) environment enables sites to verify their development efforts against .NET Passport servers without access to real-world .NET Passport user identifications and profiles. While in PREP mode, prospective .NET Passport participating sites can manipulate data, create new users, and run other tests against the user base without affecting existing deployed .NET Passport sites.

• Production: The .NET Passport Production environment is shared by all working and approved .NET Passport participating sites after they are deployed to the public.

Testing and Preproduction (PREP)

You can determine whether your site is in the default installation environment by checking the Site ID field in the Passport Manager Administration utility. If the value in the Site ID field is 1, your site is in the default installation environment. While your site is in this environment, you can perform an initial evaluation of the single sign-in service (SSI) and test any dynamic content on your site against the Passport Manager object. You can develop your Web site and any applications on your site before registering your site and requesting a site ID, or while you are waiting for the site ID and key after registration. After you have a site ID, there should be no reason to use the default installation environment again. The restrictions imposed by this mode are intended only to prevent developers from accessing certain .NET Passport features before having signed the necessary agreements or contracts.

Limitations in the Default Installation Environment

The following operational limitations exist in the default installation environment:

• Cannot read full core profile data or profile cookies: A Web site running in the default installation environment indicates that the administrator has not yet signed the necessary agreements that specify a site's requirements for privacy. For this reason, a site running in the default installation environment cannot access all .NET Passport user information. .NET Passport user information displayed on a test site contains several fields of default placeholder values, as generated by the logon server.

• Cannot use co-branding: Co-branding support is dependent on several URLs that you must provide when registering as a .NET Passport participating site. Until you register and provide these URLs, the co-branding logo and text exist as placeholders. For details about how to implement co-branding after your site has registered as a .NET Passport participating site, see ".NET Passport Cobranding Overview" in .NET Passport SDK Help.

• Cannot sign users out from sign-out page: On a registered .NET Passport site, when members choose to sign out by clicking the .NET Passport sign-out link, they are redirected to a central page that enables deletion of all .NET Passport cookies from all of the sites the member visited during the session. This is not the case in the default installation environment, so .NET Passport cookies remain on the user's browser until the user closes the browser entirely. If the .NET Passport user chose to save their password (thus making all session cookies persistent cookies), .NET Passport cookies written in the test site's domain are still not deleted. For this reason, when testing browser behavior in the default installation environment, you may occasionally need to quit the browser to reproduce a clean .NET Passport sign-in.

Testing Passport with Active Server Pages

If your Web site uses Active Server Pages (ASP) to query information from the Passport authentication ticket, you must create a Passport Manager object. The Passport Manager object is a server-side object for .NET Passport single sign-in and profile services. The Passport Manager object uses cookies and query string data as intermediaries for querying a central user store.

To create a Passport Manager object in an ASP page, use the ASP Server.CreateObject method to create a local object reference as follows:

set oMgr = Server.CreateObject("Passport.Manager")

The Passport Manager object should only be created once on each ASP page. Multiple object instantiations on a single page can lead to unexpected results when the page loads or unloads. Also, multiple instantiations will slow performance with extra memory overhead and multiple encryption and decryption of the same cookies. One way to assure a single instantiation is to create the object only once in a header file that is included on each page.

Do not create the Passport Manager object in an ASP application in Session or Application scope, unless you are specifically using that instance for utility methods such as GetDomainAttribute or DomainFromMemberName (with input parameter).

The following code sample instantiates the Passport Manager object in an ASP page to obtain user information from a .NET Passport cookie. Web sites running in the default installation environment return generic values. Web sites running in PREP or Production environments return valid user information.

%
'
' Instantiate the Passport Manager.
'
Set oMgr = Server.CreateObject("Passport.Manager.1")
'
' Use HTTPS if SecureLevel > 1.
'
thisURL = Server.URLEncode("https://" & Request.ServerVariables("SERVER_NAME") & Request.ServerVariables("SCRIPT_NAME") ) signoutURL = Server.URLEncode("https://" & Request.ServerVariables("SERVER_NAME") & "/signout.asp")
If oMgr.IsAuthenticated(3600,FALSE) Then
'
' Convert the binary PUID to a hexadecimal format for displaying.
'
strMemberIDHigh = oMgr.Profile("MemberIDHigh")
strMemberIDLow = oMgr.Profile("MemberIDLow")
strHex = Hex(strMemberIDHigh)
strPUID = String(8 - Len(strHex), "0") & strHex
strHex = Hex(strMemberIDLow)
strPUID = strPUID & String(8 - Len(strHex), "0") & strHex

For more information, see "Passport Manager Methods" or "Passport Manager Properties" in .NET Passport SDK (starting with version 2.1) Help.

Testing ASP Against the .NET Passport Default Installation Environment

To test ASP against the .NET Passport default installation environment

1. Enable .NET Passport authentication on a virtual directory. You can use the code sample above in the Default.asp page and include the Default.asp page in the virtual directory. To learn more about enabling .NET Passport authentication on a Web site or a virtual directory, see Enabling .NET Passport Authentication in IIS 6.0.

   Note

   Microsoft Windows XP client computers used to test .NET Passport must be configured for .NET Passport default installation and PREP environments. To configure your Windows XP client computers to connect to these environments, see ".NET Passport SDK: System Requirements" in .NET Passport SDK (starting with version 2.1) Help. More specifically, read the section titled "Client Computer Requirements."

2. On a remote client computer, open a Web browser, type the virtual directory URL in the address bar, and press ENTER. The client connects to the Web site and is then redirected to the .NET Passport server. Passport reads the site ID as 1, which tells the Passport service that your server is still in the default installation environment. You are then redirected to the .NET Passport test environment for credential authentication. Windows 2000 or earlier clients open a logon Web page. Windows XP clients (configured according to "Client Computer Requirements" in .NET Passport SDK Help) open the Stored User Names and Passwords dialog box.

3. Type valid .NET Passport credentials and click OK.

4. .NET Passport validates the credentials and displays hard-coded, generic user information. The server running IIS collects a cookie with the generic information. The display does not contain any confidential material. The .NET Passport User ID (PUID) is not real because, at this point, your IIS server has not established a contract with .NET Passport.

Mapping to Active Directory

In certain scenarios (for example Business-to-Business [B2B] or Business-to-Consumer [B2C]) you might want to set up Access Control Lists (ACL) on specific Web pages or content and then have selective members or groups access the Web pages using .NET Passport authentication. As an example, a large company with multiple vendors might establish a timecard reporting site for all contingent staff. By setting up the timecard reporting online, vendors can access the Web page from any Web browser, and the company can control security using Passport authentication.

To configure.NET Passport authentication that uses ACLs, the .NET Passport user must have a PUID mapped to an account in Active Directory directory service. A Passport ticket contains the PUID. The initial mapping of PUIDs to accounts in Active Directory is called provisioning. Provisioning is described later in this topic.

The Active Directory attribute altSecurityIdentity is used to map the Passport user to an Active Directory account. The value of altSecurityIdentity looks like this: kerberos:0124ABCD78787878@domain.com. This essentially is a User Principal Name (UPN) where the PUID is the UPN prefix and everything after the "@" is the UPN suffix. The UPN suffix determines where the mapping lives. The UPN suffix should be the domain where the mapping is created or exists. In other words, in the sample mapping kerberos:0124ABCD78787878@domain.com, domain.com is the UPN suffix. The UPN suffix can be configured in the IIS authentication dialog. The UPN suffix value must be the same as the value configured in the IIS authentication dialog or the same as the domain name of the server.

The IIS metabase property AuthFlags contains the available settings for Windows authentication schemes and the file access authentication flags. By default, IIS 6.0 with .NET Passport authentication enabled tries to map the .NET Passport user to an account in Active Directory. This default behavior can create performance overhead for sites that do not want to use .NET Passport Active Directory mapping. The mapping behavior can be controlled by the PassportRequireADMapping flag. The flag values are:

• PassportRequireADMapping set to 0: IIS does not attempt Active Directory mapping. The request is handled as Anonymous User.

• PassportRequireADMapping set to 1 (default setting): In this situation the worker process must have Trusted Computing Base (TCB) privileges, which means that the worker process acts as part of the operating system. IIS then attempts to map to an Active Directory account (called LsaLogonUser). If this attempt fails, the request is handled as Anonymous User.

• PassportRequireADMapping set to 2: IIS enforces a mapping from the .NET Passport account to an Active Directory account before returning the requested Web page. If the mapping fails, IIS returns a 401 error.

For .NET Passport mapping to work, the account used for the IIS worker process must meet the following criteria:

• The IIS worker process must be running as LocalSystem if the computer is a domain member. To change the account on the worker process, see Configuring Worker Process Identities.

• If using a service account, the domain account must have TCB privilege on the local box (meaning, the account acts as part of the operating system).

• The account must be a member of the pre-Windows 2000 compatible access group, or have Read access to list group memberships.

The following WMI script sets the PassportRequireADMapping flag in the IIS metabase:

dim g_PPADMapping : g_PPADMapping = 0
call ValidateArgs(WScript.Arguments)
Set g_Locator = CreateObject("WbemScripting.SWbemLocator")
Set g_IIS = g_Locator.ConnectServer ("","root\MicrosoftIISv2","", "")
Set g_NodeObj = g_IIS.Get("IIsWebVirtualDirSetting='" & WScript.Arguments(0) & "'")
g_NodeObj.PassportRequireADMapping.Value = g_PPADMapping
g_NodeObj.Put_
WScript.Echo WScript.Arguments(0) & "/PassportRequireADMapping changed to: " & g_PPADMapping
sub ValidateArgs(args)
      if args.Count <> 2 then
            call Usage
      end if
      if args(1) = "no" then
            g_PPADMapping = 0
      elseif args(1) = "try" then
            g_PPADMapping = 1
      elseif args(1) = "enforce" then
            g_PPADMapping = 2
      else
            call Usage
      end if
end sub
sub Usage
      WScript.echo "Usage: " & WScript.ScriptName & " metabase_path no|try|enforce"
      WScript.Echo "Example: " & WScript.ScriptName & """w3svc/1/root/passportvdir enforce"""
      WScript.Echo " ------- Enforces mapping for virtual directory passportvdir"
      WScript.Quit
end sub

Provisioning

To establish ACLs on a Web page for .NET Passport authentication, PUIDs need to be mapped to a corresponding account in Active Directory. This process is called provisioning. The sample code in this section provisions PUIDs to Active Directory accounts. To provision the Active Directory, you must have administrator credentials on the Active Directory server. Normally this provisioning is accomplished by a .NET Passport-enabled Web page that collects information about the .NET Passport user and then saves the data so an administrator can perform the provisioning against Active Directory.

The following sample code is taken from Subscribe.asp. Use this code on your .NET Passport-enabled ASP page to collect .NET Passport user IDs and create Active Directory user accounts with the .NET Passport mapping.

%
 '
 ' Instantiate Passport Manager.
  '
 Set objPassportManager = Server.CreateObject("Passport.Manager.1")
 '
 ' Get any available information about the user from Passport.
 '
 strCurrentUserEmail = objPassportManager.Profile("PreferredEmail")
 strMemberIDHigh = objPassportManager.Profile("MemberIDHigh")
 strMemberIDLow = objPassportManager.Profile("MemberIDLow")
 strHex = Hex(strMemberIDHigh)
  '
 ' Convert the PUID into the correct form.
 '
 strPUID = String(8 - Len(strHex), "0") & strHex
 strHex = Hex(strMemberIDLow)
 strPUID = strPUID & String(8 - Len(strHex), "0") & strHex
 strLastName = objPassportManager.Profile("LastName")
 strFirstName = objPassportManager.Profile("FirstName")
 '
 ' Connect to Active Directory and find the default naming context for the default domain.
 '
 set rootDSE = GetObject("LDAP://RootDSE")
 if Err.Number <> 0 then
  Response.Write "GetObject Error = " & Hex(Err.Number) & " (Source: " & Err.Source & ")"
 end if
 Err.Clear
 strDomainDN = rootDSE.Get("defaultNamingContext")
 if Err.Number <> 0 then
  Response.Write "Get Domain DN Error = " & Hex(Err.Number) & " (Source: " & Err.Source & ")"
 end if
 Err.Clear
 strdnsName = rootDSE.Get("dnsHostName")
      FirstDot = Instr( strdnsName, "." )
      strDomainName = Right( strdnsName, Len( strdnsName ) - FirstDot )
 strContainerDN = "cn=users, " & strDomainDN
 
 ' Bind to the user's container.
 set cont = GetObject("LDAP://" & strContainerDN )
 if Err.Number <> 0 then
  Response.Write "GetObject Users Container Error = " & Hex(Err.Number) & " (Source: " & Err.Source & ")"
 end if
 Err.Clear
 ' Create the user account.
 Set user = cont.Create("user", "cn=" & strCurrentUserEmail)
  if Err.Number <> 0 then
  Response.Write "Create User Error = " & Hex(Err.Number) & " (Source: " & Err.Source & ")"
 end if
 user.put "samAccountName", strPUID
 strFullAccountName = strPUID & "@" & strDomainName
  user.put "altSecurityIdentities", "Kerberos:" & strFullAccountName
      ' Set the UPN of the user to equal the PP e-mail address.
      user.put "userPrincipalName", strCurrentUserEmail
      user.put "givenName", Request.form("fname")(1)
      user.put "sn", Request.form("lname")(1)
 '
      '   IMPORTANT!!!
      ' Before going live with a site based on this sample code,
      ' the following must be changed so that a random password
      ' is assigned to each account. A recommended way to do this
      ' is to use the CAPICOM Utilities.GetRandom function.
 '
      user.put "userPassword", "89sd53ET!23kL"
 ' Write the property cache.
 user.SetInfo
 ' Refresh the property cache.
 user.GetInfo
 ' Clear the account disabled flag and set neccessary flags.
 flags = user.get("userAccountControl")
 flags = flags OR "H00010000
 flags = flags AND "HFFFFFFFD
 user.put "userAccountControl", flags
 user.SetInfo
%

Configuring for Preproduction

Real-world .NET Passport users probably do not have existing e-mail names within the PREP environment. Part of your site's development and testing effort might require that you first create a store of users within the PREP environment and then use these accounts for testing against the .NET Passport authentication and profile-access portions of your site's code. The .NET Passport server code that runs the services in the PREP environment is essentially identical to the code that runs live in the Production environment; Production and PREP are released in tandem. This means that going live should be a matter of simply stopping the servers on a site currently running against the PREP environment, reconfiguring Passport Manager on those servers to run against the Production environment instead, and then restarting the servers.

For more information about getting a PREP site ID, see "Registering Your .NET Passport Site" in the .NET Passport SDK (starting with version 2.1) Help. For more information about PREP Passports, see "Get a PREP Passport" and "Sign in to PREP Passport" in .NET Passport SDK (starting with version 2.1) Help. Also, see "Going Live: Deploying Passport Manager and Site Code."

Upon completion of the registration process, you will see a confirmation page that indicates your new .NET Passport sign-in name. This is the name you will use while in the development phase.

Configuring for Production

All Microsoft .NET Passport users already have an account in this environment. Users of Microsoft MSN Internet Access and MSN Explorer, as well as users who registered directly at the Passport.com Web site, also have passports in this environment. Within the Production environment, sites can expect to handle many real-world .NET Passport users who might already have been authenticated at various other Passport participating sites.

To deploy the .NET Passport code of your site, the Passport Manager server-side object must be reconfigured to work against the Production environment. To deploy against the Production environment, your site must also register for a site ID in the Production environment, and must supply some configuration information about your site that is specific to the Production deployment. Approval of a site ID in the Production environment might require some basic remote checking of your site's .NET Passport implementation by the .NET Passport team, and might also require some additional contracts or agreements.

To deploy against the .NET Passport Production environment, see "Registering Your Passport Web Site" in the .NET Passport SDK (starting with version 2.1) Help. To disable the default installation environment and enable normal operation, enter a different site ID in the Site ID field and commit changes. Note that if you change the site ID to something other than 1, a matching encryption key must also be installed. The key, as well as the unique site ID assigned to any particular participating site, can be obtained only by registering as a .NET Passport participating site.

Passport Manager Administration Utility

The Microsoft Passport Manager Administration utility is a graphical user interface (GUI) alternative to editing the registry when changing Passport Manager object settings. The most common use of the Passport Manager Administration utility is to change the default settings. For details about how defaults can be set and affect the behavior of Passport Manager methods, see "Setting Passport Manager Defaults" in .NET Passport SDK Help.

To access the Passport Manager Administration utility

1. From the Start menu, click Run.

2. In the Open box, type msppcnfg.exe, and click OK.

Related Information

• For helpful whitepapers that include information about everything from the benefits of enabling .NET Passport on your Web sites, to the .NET Passport Software Development Kit (SDK), see the Microsoft .NET Passport Web site.

• For more information about IIS and Web site security, see Security in IIS 6.0.