Share via

IPassportManager::LogoTag

  • Article

IPassportManager::LogoTag

Returns an HTML snippet that includes an IMG source string for a Microsoft® .NET Passport link. The link image displays either Sign In if no valid Ticket cookie is detected or Sign Out if a valid Ticket cookie is detected. Each IMG source includes an associated HREF used to sign in or sign out, as appropriate.

Important  This method does not take advantage of the .NET Passport authentication capabilities that are built into Microsoft® Windows® XP. The LogoTag2 method of the IPassportManager2 interface does use this functionality. For more information, see IPassportManager2::LogoTag2.

Syntax

HRESULT LogoTag  (
  VARIANT returnUrl,
  VARIANT TimeWindow,
  VARIANT ForceLogin,
  VARIANT coBrandArgs,
  VARIANT lang_id,
  VARIANT bSecure,
  VARIANT NameSpace,	
  VARIANT KPP, 
  VARIANT SecureLevel,
  BSTR*   pVal
);

Parameters

  • returnUrl
    [in, optional] A VARIANT (should be VT_BSTR) used for the case in which the Sign In link is returned. This sets the URL of the location to which the Login server should redirect users after sign-in is complete. If returnUrl is left empty, the registry default is used. If adding your own query string variables to a vRU URL, use only one query string variable. Do not include special characters that require separate encoding as part of such a variable, and do not use the following variable names, which are reserved for use by .NET Passport: "t", "p", "f". For more information, see Saving State. Using the Server.URLEncode method, URL-encode this string. (See IServer::URLEncode in IIS reference.) If returning to a port other than 80, specify the port in the URL. It must point to a named file, not just a root. In the case in which the Sign Out link is returned, returnUrl specifies where users return after sign-out is complete. If SecureLevel is specified, returnUrl must be HTTPS.
  • TimeWindow
    [in, optional] A VARIANT (should be VT_I4) representing time value, in seconds. This specifies the interval during which users must have last signed in. If TimeWindow is left empty, then the registry default is used. If given, this value must be between 20 and 2678400 (between 20 seconds and 31 days).
  • ForceLogin
    [in, optional] A VARIANT (should be VT_BOOL), used for the case in which the Sign In link is returned. If set to VARIANT_TRUE, the Login server will compare TimeWindow against the time since the user last signed in. If set to VARIANT_FALSE, then the Login server will compare TimeWindow against the last time the Ticket was refreshed.
  • coBrandArgs
    [in, optional] A VARIANT (should be (VT_BSTR) that specifies variables to be appended as query string variables to the URL of the participating site's cobranding template script page. Using the Server.URLEncode method, always URL-encode the entire string (See IServer::URLEncode in the IIS reference.) The cobranding template base URL is specified at initial registration. If left blank, this parameter defaults to registry default, if any. Do not add the question mark character (?) to form the query string. The string should form one or more key-value pairs with = (equal sign) between key and value, and an ampersand (&) between key-value pairs if more than one is given. For information about using coBrandArgs variables to modify cobranding at run time, see .NET Passport Cobranding Overview.
  • lang_id
    [in, optional] A VARIANT (should be VT_I4) specifying the language in which the Login page should be displayed to the user. This value is the integer representation of a standard locale ID (LCID). For example, U.S. English (EN/US, the default) is 1033. For a table of LCIDs, see Localization and .NET Passport Services.
  • bSecure
    [in, optional] A VARIANT (should be VT_BOOL) that declares whether this method is being called from an HTTPS (SSL) page. If bSecure is set to VARIANT_TRUE, then the appropriate Graphics Interchange File (GIF) image will also be served from the .NET Passport domain authority through HTTPS. If bSecure is left blank or set to VARIANT_FALSE, then the link image is served HTTP.
  • NameSpace
    [in, optional] A VARIANT (VT_BSTR).
  • KPP
    [in, optional] A VARIANT (VT_I4). Use only if implementing Microsoft® Kids Passport service; otherwise, leave default. By setting KPP to different levels on a per-page basis, a site can allow or deny access to children only where strictly necessary. For more information on the KPP parameter, see Checking for Consent.
  • SecureLevel
    [in, optional] A VARIANT (should be VT_INT). Declares one of three security level options for the .NET Passport sign-in:
    SecureLevel value Description
    0 (or unspecified) 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 for persistent sign-in.
    10 Sign-in UI is served HTTPS from the .NET Passport domain authority. Requires that vRU 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. For more information, see SSL Sign-In.
    If the client is .NET Passport-aware, then the HTTP/HTTPS distinction is not relevant, because the login UI is integrated with the client.
  • pVal
    [out, retval] A pointer to a BSTR value. Returns an HTML snippet specifying one of two URL/GIF combinations, depending on whether a valid Ticket cookie was found on the client computer.
  • If a valid Ticket was found, then returns the string for the Sign Out image source and HREF tag.
  • If no Ticket was found, returns the string for the Sign In image source and HREF tag.

For information about how to call methods with optional VARIANT inputs, see Passing Empty Variants.

Return values

Returns one of the following values:

S_OK Success.
PP_E_NOT_CONFIGURED Passport Manager configuration settings in registry are missing or bad.
PP_E_INVALID_TIMEWINDOW TimeWindow parameter was less than 20 or greater than 2678400, or given as the wrong variant type. This error could be returned either if TimeWindow came from a specific call or if TimeWindow came as a default from registry values.
E_INVALIDARG A supplied input parameter was not a variant or was a variant type that could not be coerced into an acceptable type for that parameter. This error will be returned if bad values came from a specific call or if bad values were from registry defaults.

Remarks

Several of the optional input parameters are used to form query string arguments added to the Login server URL when the HREF for the Sign In link is returned. These query string arguments are then processed by the Login server after the user actually clicks the Sign In link. They determine whether the Login server can refresh credentials silently or must display the Login form.

Because of security concerns, the .NET Passport Login server URL cannot be loaded into a frameset; it must always be the top window in the object model. Specify target="_top" for any HREF that points to the Login server if your site uses frames. (This may require parsing and reforming the output of the LogoTag method if you intend to include the .NET Passport link in a framed document.)

The vTimeWindow, vForceLogin, and vRU parameters of IPassportFastAuth2::LogoTag are used to form parameters added to the Login server URL query string when the sign-in HREF is returned. These query string arguments are processed by the Login server only after the user actually clicks the Sign In link. They determine whether the Login server can refresh silently or will always display the sign-in form.

If your site has not specified a global sign-out URL at site registration time, you can choose a dynamic location to which to return users after they click a .NET Passport Sign Out link from your site. By using IPassportManager::get_HasTicket, you can anticipate whether a LogoTag call will return the Sign In or the Sign Out case and then use the returnUrl parameter of LogoTag to specify the URL to which to return users after sign-out. If developing in test mode, then signing out will fail to erase local domain cookies automatically; the cookies will be deleted only by quitting the browser session. For more information, see Implementing Sign-Out and Deleting Cookies.

Microsoft .NET Passport links may not display correct state to the user while the Passport Manager object is in stand-alone mode. Clicking either a Sign In or Sign Out link while the Passport Manager object is in stand-alone mode takes the user to the configured DisasterURL, if any. Occasionally the actual image required by the link will be unavailable whenever stand-alone mode is necessary.

Some input parameters of IPassportFastAuth::LogoTag can be specified as default values stored in the registry, such that a call to IPassportFastAuth2::LogoTag could leave some input parameters blank and revert to the registry default values. If values are given for any parameter in a specific LogoTag call, the input parameters will override the default values. Use the Passport Manager Administration utility to check or set defaults for any methods that use vRU, vTimeWindow, vForceLogin, vCoBrand, or vLangId.

Unlike the LoginUser method, LogoTag does not have an ExtraParams parameter to override the default Cobrand Instruction Text specified during site registration.

See Also

IPassportManager::get_HasTicket | Test Mode | Stand-Alone Mode | Passport Manager Administration Utility