Passport Manager Administration Utility (C#)
.jpg)
Passport Manager Administration Utility
The Passport Manager Administration utility is a graphical-interface alternative to editing the registry to change Passport Manager settings. The most common use of the Passport Manager Administration utility is to change the default parameter values used by PassportIdentity methods if optional parameters are omitted when the methods are called. The term "Passport Manager" refers to the interface with Microsoft® .NET Passport servers that is controlled in ASP.NET code by instances of the PassportIdentity class.
Although some parameters of .NET Passport methods are overloaded and can be considered optional, these methods (for example, PassportIdentity.LoginUser) still generate URLs or results that reflect 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 PassportIdentity 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 property 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 specified time window.
A False default for Force Login means that any Ticket within the time window is acceptable either to the IsAuthenticated property 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
- Click Start, point to Programs, and then to Microsoft Passport.
- Click Passport Manager Administration Utility.
The following figure shows the main user interface of the Passport Manager Administration utility.
.gif)
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 iTimeWindow parameter used in PassportIdentity object methods LoginUser, AuthURL2, IsAuthenticated, and LogoTag2, among others. iTimeWindow specifies the maximum duration allowed between either silent or forced manual sign-in to a participating site. iTimeWindow 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 PassportIdentity object on requests to the Login server. This becomes the default value of the iLangID parameter, also called the LCID, used by PassportIdentity object methods AuthURL2 and LogoTag2, among others. Users see different localized text at the Login server depending on this LCID. If the LCID you require is not available, you can add it 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 fForceLogin parameter used in PassportIdentity object methods LoginUser, AuthURL2, GetIsAuthenticated, and LogoTag2, among others. Specifies whether user sign-ins falling outside of iTimeWindow 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 PassportIdentity 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, 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 PassportIdentity 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 PassportIdentity object 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 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 is running in test mode. |
| Return URL text box |
Blank | Used to fill in defaults for the strReturnURL parameter given in PassportIdentity object methods LoginUser, AuthURL2, and LogoTag2, among others. |
| Cobrand Args text box |
Blank | Used to fill in defaults for the strCoBrandedArgs parameter given in PassportIdentity object methods LoginUser, AuthURL2, and LogoTag2, among others. |
| Disaster URL text box |
Blank | Specifies the URL used to replace any .NET Passport network server URL in cases in which the Passport Manager is configured to run in stand-alone mode. |
| Cookie Domain text box |
Blank | The domain to which the PassportIdentity 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 PassportIdentity 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 PassportIdentity 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 PassportIdentity 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 PassportIdentity 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 PassportIdentity object should write Secure cookies. Secure cookies are used as verification for SSL sign-in when calling the IsAuthenticated property. |
| Secure Path text box |
Blank | Within the domain, the path to which Profile cookies are written. |
| Secure Level text box |
Blank | Displays the default per-site security level of the sign-in.
Valid values are:
|
| Commit Changes button |
N/A | Click to assign values in current Passport Manager Administration utility controls to the Passport Manager and the associated PassportIdentity instances, 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 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 PassportIdentity 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 set on each method call. Other attributes as set in the Passport Manager Administration utility do not necessarily affect PassportIdentity method defaults directly.
See Also
Configuring Multiple Sites | Stand-Alone Mode | Test Mode | Implementing Sign-Out and Deleting Cookies | PassportIdentity.LoginUser | PassportIdentity.AuthURL2 | PassportIdentity.LogoTag2 | Installing the .NET Passport SDK and Passport Manager