Passport Manager Administration Utility

Passport Manager Administration Utility

The Passport Manager Administration utility is a graphical-interface alternative to editing the registry to change Passport Manager object settings. The most common use of the Passport Manager Administration utility is to change the defaults that Passport Manager methods use if certain optional parameters are omitted when the methods are called.

Although some parameters of Microsoft® .NET Passport methods are listed as optional, these methods, such as PassportManager.LoginUser, still generate URLs or results that reflect inherent default values when called. These default parameter values can be used to provide consistent site-wide values, such as the required time window within which all users must be authenticated.

The following are the primary defaults that affect Passport Manager implementation:

• Time Window

  Change this value to the default time window you wish to set. The time window specifies how old a Ticket can be before the IsAuthenticated method returns False for an otherwise valid Ticket. It also qualifies how old a Ticket as submitted to the Login server can be without requiring a refresh for purposes of the LoginUser, AuthURL2, or LogoTag2 methods. The default as installed is 1800 seconds (equal to 30 minutes).

• Force Login

  Change this value to be either True (checked) or False (unchecked).

  True specifies that the Ticket as read by the IsAuthenticated method must represent a refresh in which the user physically enters a password, not a silent refresh, in order for IsAuthenticated to return True itself. A True default for Force Login also changes the behavior at the Login server for any user sent there by URLs derived from the LoginUser, AuthURL2, or LogoTag2 methods. Specifically, the Login server does not silently refresh and always asks for a password if the existing Ticket is past the supplied time window.

  A False default for Force Login means that any Ticket within the time window is acceptable either to the IsAuthenticated method or to handling at the Login server as accessed by means of the AuthURL2 or LogoTag2 output URLs (or a LoginUser redirect).

• Language ID

  If a server on your site is dedicated to a particular language or locale, it may be useful to set the Language ID on that server always to be a consistent value rather than declaring the locale ID (LCID) in each method call. The Language ID declares the language that .NET Passport service pages (such as Sign-in and Registration) render in when obtained with the URL results of the LoginUser, AuthURL2, LogoTag2, or GetDomainAttribute methods. There may still be reasons to declare an LCID by method call or user access if your site expects to handle multiple languages and uses either .NET Passport profile information or browser sniffing to determine the user's probable language choice.

To run the Passport Manager Administration utility

1. Click Start, point to Programs, and then to Microsoft Passport.
2. Click Passport Manager Administration Utility.

The following figure shows the main user interface of the Passport Manager Administration utility.

Passport Manager Administration Utility

The following table describes the various elements of the user interface (UI) and their default values (if applicable).

Dialog box element	Default	Description
Web Site Name drop-down list box	<default>	Displays the "friendly name" of the currently selected site configuration.
New button	N/A	When clicked, displays the Add a New Web Site dialog box used to create a new site configuration. The newly created configuration subsequently appears in the Web Site Name drop-down list box.
Host Name text box	Blank	Displays the host name of the currently selected site configuration. Not displayed for the default site's configuration.
IP Address text box	Blank	Displays the IP address of the currently selected site configuration. Not displayed for the default site's configuration.
Remove button	N/A	When clicked, removes the site configuration currently selected in the Web Site Name drop-down list box.
Server Name text box	Localhost	Displays the name of the server hosting Passport Manager. (The value is read-only here, but can be set using the Computer menu).
Install Dir text box	c:\Program Files\Microsoft Passport	Displays the directory where the .NET Passport Software Development Kit (SDK), but not the Passport DLL, is installed (a read-only value).
Time Window combo box	1800	Used to fill in defaults for the TimeWindow parameter used in Passport Manager and FastAuth object methods LoginUser, AuthURL2, IsAuthenticated, and LogoTag2. TimeWindow specifies the maximum duration allowed between either silent or forced manual sign-in to a participating site. TimeWindow must be >=100 and <=1000000.
Language ID combo box	1033, English	This drop-down list box allows you to set the language preference sent by the Passport Manager object on requests to the Login server. This becomes the default value of the lang_id parameter, also called the LCID, used by Passport Manager and FastAuth object methods AuthURL2 and LogoTag2. Users see different localized text at the Login server depending on this LCID. If the LCID you require is not available, you can add the new LCID by selecting all the text in the text box and then typing in a new LCID number. If the LCID is included in the Passport Manager Administration utility support code, this will display the language name next to the new LCID.
Force Sign In check box	Unchecked	Used to fill in defaults for ForceLogin parameter used in Passport Manager and FastAuth object methods LoginUser, AuthURL2, IsAuthenticated, and LogoTag2. Specifies whether user sign-ins falling outside of TimeWindow are allowed to be silent or require the user to enter the password again.
Disable Cookies check box	Unchecked	Disables the use of cookies with the Passport Manager object. If you disable cookies, all profile information must be passed page-to-page using the query string. This practice is not recommended, because it requires a large amount of query string handling, using the FastAuth interface, and writing code to handle requests at the HTTP level.
Stand Alone Mode check box	Unchecked	When checked, sets the Passport Manager installation to stand-alone mode, which is for cases in which all Login servers at .NET Passport are down. Stand-alone mode treats all existing user cookies as valid and does not contact the Login server or compare timestamps, effectively disabling any application programming interface (API) methods that would ordinarily reject a user with an old Ticket.
Verbose Mode check box	Unchecked	When checked, sets this Passport Manager installation to verbose mode, which helps to enable better debugging through a text log of all Passport Manager method calls and operations. Verbose mode should be used only to debug specific problems, because it slows performance and generates a large text log if left on for extended periods.
Current (environment) controls	Depends on initial installation	Use this control to reconfigure the environment that Passport Manager will run against.
Change button	N/A	Click this button to open the Choose Environment dialog box in which you can select an environment from one of the options in the Environment section.
Enable Manual Refresh check box	Checked	Sets a registry entry (NSRefresh) when checked. This allows the passporttest Web site (https://localhost/passporttest/default.asp) to receive the latest version of the Partner.xml file. You cannot get the latest Partner.xml from the passporttest Web site without setting this registry entry because the default.asp page checks the registry entry prior to instantiating Passport Manager and calling Refresh.
Refresh Network Map check box	Unchecked	When checked, this will cause the Passport Manager Administration utility to launch the passporttest Web site on localhost when the Commit Changes button is pressed. The appropriate query string parameters are passed to the site, which will instruct it to download the Partner.xml. After clicking Commit Changes, a MessageBox is displayed indicating that the Network Map is about to be updated. Clicking OK will cause the passporttest site to be launched as: https://localhost/passporttest/default.asp?Refresh=True&Env;=Prep&NewID;=False
Site ID text box	1	Displays the Site ID, which qualifies all communication with the .NET Passport domain authority and Nexus servers. The .NET Services Manager provides participating sites with an executable program that can be run on each Passport Manager-enabled server to install site-specific encryption keys. At this time, you should set your Site ID to the value provided in instructions sent with the key installation program, and this is generally the only time that the Site ID value should be edited. Attempting to change this value in the Passport Manager Administration utility will cause a warning message to be displayed. The initial Site ID of 1 means that this Passport Manager object is running in test mode.
Return URL text box	Blank	Used to fill in defaults for the returnURL parameter given in Passport Manager and FastAuth object methods LoginUser, AuthURL2, and LogoTag2.
Cobrand Args text box	Blank	Used to fill in defaults for the coBrandArgs parameter given in Passport Manager and FastAuth object methods LoginUser, AuthURL2, and LogoTag2.
Disaster URL text box	Blank	Specifies the URL used to replace any .NET Passport network server URL in cases in which Passport Manager is configured to run in stand-alone mode.
Cookie Domain text box	Blank	The domain to which the Passport Manager object should write Ticket and Profile cookies. Typically this should be the same as the value given by Request.ServerVariables("SERVER_NAME") for a page that uses this Passport Manager object. If you are writing cookies to a subdomain of your own domain, you should precede the domain path with a dot (".") character. For example, if your site is shopping.example.com and you want the Passport Manager object to set cookies in example.com, set the Cookie Domain entry to .example.com (note the preceding dot, a requirement for some Netscape browsers).
Cookie Path text box	Blank	Within the domain, the path to which Ticket and Profile cookies are written.
Consent Cookie Domain text box	Blank	The domain to which the Passport Manager object should write Consent cookies. Typically, this should be left blank, or at least be the same as the value given by Request.ServerVariables("SERVER_NAME") for a page that uses this Passport Manager object. Consent cookies are written by Passport Manager only if you specifically inform your .NET Passport representative that you intend to enable a "property" model, where several properties share a Ticket for authentication but each property is distinct for purposes of Kids Passport and consent. If Passport Manager is writing the Consent cookie, Consent domain entry should not match the Cookie domain, and should instead be written to a tertiary domain. Each property must be distinct for purposes of establishing unique consent status. The Consent cookie written to the tertiary domains will contain the consent status granted each individual property. The domain must still fall within the root domain specified at registration time.
Consent Cookie Path text box	Blank	Within the domain, the path to which Consent cookies are written.
Secure Domain text box	Blank	The domain to which the Passport Manager object should write Secure cookies. Secure cookies are used as verification for SSL sign-in when calling the IsAuthenticated method.
Secure Path text box	Blank	Within the domain, the path to which Profile cookies are written. Because of a known issue in which MSN® TV may request and receive secure cookies through standard HTTP connections, you may wish to establish the Secure cookie in a different domain. By disabling standard HTTP access to the Secure cookie domain at the server level, you can disable the potential for MSN TV clients to pass secure .NET Passport data in the clear. For this reason, MSN TV cannot and should not use SSL sign-in.
Secure Level text box	Blank	Displays the default per-site security level of the sign-in. Valid values are: 0 (or blank) Sign-in UI is served HTTP from the .NET Passport domain authority (default). Even using this option, there will be an intermediate transition to HTTPS on the .NET Passport server side to enable writing a Secure cookie that is set by domain authorities for the persistent sign-in option. 10 Sign-in UI is served HTTPS from the .NET Passport domain authority. Requires that return URL be an HTTPS URL; otherwise, the authentication will fail. 100 Sign-in UI is served HTTPS from the .NET Passport domain authority, and sign-in process now requires submission of a security key in addition to password. Requires that return URL be an HTTPS URL; otherwise, the authentication will fail. For more information, see SSL Sign-In.
Commit Changes button	N/A	Click to assign values in current Passport Manager Administration utility controls to the Passport Manager object, and assign these values to the underlying registry keys. You must click Commit Changes in order to actually make any configuration changes.
Undo Changes button	N/A	Click to redisplay saved registry values. This does not undo any changes committed to the registry. Create .ppi files as backups if there is a need to revert to previously saved or overwritten registry settings.

Notes

• Consistency between servers

  When changed, many settings in the Passport Manager Administration utility display a message window informing you that changes to specific Passport Manager object values should be consistent across servers in your site. In general, a site's Passport Manager-enabled servers should all have the same Passport Manager Administration utility settings, so that cookies written by one installation will not react differently when the user returns to the site and rotates to another server. You can use the Select Server command from the Computer menu to access and configure any remote server that is accessible on the LAN and already has Passport Manager installed.

• Cookie path and domain

  Make sure that all required installations of Passport Manager on your site can both read and write to a common path and domain location. If they cannot, cookies set by one Passport Manager instantiation may not be able to read the cookies set by another. A symptom of this would be that a user does not always appear to have a Ticket even though he or she signed in to .NET Passport and your site before.

• Saving text-file versions of Passport Manager Administration utility settings

  From the File menu, the Save and Save As commands save all current Passport Manager Administration utility values as a text file with the extension ".ppi," but they do not commit the values to the registry. (To commit values to the registry, click the Commit Changes button.) These text (.ppi) files are useful for configuring multiple servers in exactly the same way without having to extract the required keys to make a .reg file. From the File menu, choose Open to load a previously saved .ppi file and assign these values to the various controls in the Passport Manager Administration utility. A common use for this feature would be to save all settings on a single computer as a .ppi file, use the Computer menu to access a remote server's configuration, load the saved .ppi file, click Commit Changes to commit those settings to the remote computer, and repeat as necessary to propagate all settings identically across multiple computers.

• Cobrand Args and Return URL

  Setting Cobrand Args and Return URL as site-wide defaults does not make sense in most cases; these should probably be left blank and be set on each method call. Other attributes as set in the Passport Manager Administration Utility do not necessarily affect Passport Manager or Passport FastAuth method defaults directly.

See Also

Configuring Multiple Sites | Stand-Alone Mode | Test Mode | Implementing Sign-Out and Deleting Cookies | Manager.LoginUser | Manager.AuthURL2 | Manager.LogoTag2 | Installing the .NET Passport SDK and Passport Manager