次の方法で共有

IPassportManager2::LoginUser

  • [アーティクル]

IPassportManager2::LoginUser

Logs the user on, either by outputting a 302 redirect URL, or initiating a Microsoft® .NET Passport-aware client authentication exchange. This method supports .NET Passport-aware client applications and the Credentials Manager used in Microsoft® Windows® XP operating system.

When LoginUser logs the user on by outputting a 302 redirect URL, the .NET Passport user's client is determined to not be inherently .NET Passport-aware, and all authorization interactions default to the mechanisms used in previous .NET Passport releases. This method writes a 302 redirect into the HTTP response sent to the user in the page in which LoginUser is invoked. All other elements of the response will thus be discarded. The 302 redirect points the user to the .NET Passport Login server. After authentication, the user will again be redirected back to the returnUrl specified in LoginUser method parameters. This method replaces the previous Response.Redirect to Login server usage. This sequence requires that the MSPPFLTR.DLL is installed and running as an ISAPI filter at the global level of the participating Web site.

When LoginUser logs the user on by initiating a .NET Passport-aware client, authentication exchange authorization is handled through exchange of information in a series of HTTP challenges and responses, authentication credentials are potentially storable by the client, and the client can present its global authentication UI instead of displaying the HTML page used for .NET Passport UI in default browser clients.

Do not call this application programming interface (API) from within a frameset.

There are some policy restrictions on use of this method in certain scenarios. For more information, see Adding a Personal Consent Page.

Syntax

HRESULT LoginUser  (
  VARIANT returnUrl,
  VARIANT TimeWindow,
  VARIANT ForceLogin,
  VARIANT coBrandArgs,
  VARIANT lang_id,
  VARIANT NameSpace,	
  VARIANT KPP, 
  VARIANT SecureLevel,
  VARIANT ExtraParams, 
);

Parameters

  • returnUrl
    [in, optional] A VARIANT (should be VT_BSTR) that sets the URL to which the Login server should redirect users after sign-in is complete. Using the Server.URLEncode method, always URL-encode this string. (See IServer::URLEncode in IIS reference.) If returnUrl is left empty, the registry default is used. If adding query string variables to a returnUrl, 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. 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. 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). 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 participant's cobranding template script page. Using the Server.URLEncode method, always URL-encode the entire string given to this parameter. (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.
  • 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 about 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 option.
    10 Sign-in UI is served HTTPS from the .NET Passport domain authority. Requires that returnUrl 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.

  • ExtraParams
    [in, optional] A VARIANT (should be VT_BSTR) that may contain comma-separated name-value pairs to be inserted directly into the challenge authentication header, specifically for .NET Passport-aware authentication interaction.

    The primary purpose of this parameter is to pass the cbtxt variable. cbtxt is used to specify customizable text in the Credentials Manager dialog box, and is typically used to identify this authentication as being specifically a .NET Passport authentication.

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

Return values

Returns one of the following values:

S_OK Success.
PP_E_NOT_CONFIGURED Passport Manager object configurations in the registry are either missing or incorrect.
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

Important  This method inherently includes a 302 redirect. If this behavior is not desired, use IPassportManager3::GetLoginChallenge and redirect to the output URL, making sure to also submit any headers returned by GetLoginChallenge. Alternatively, use IPassportManager2::AuthURL2 to determine the Login server URL and then handle redirection as you see fit.

Several of the optional input parameters are used to form query string arguments added to the Login server URL when this method is called. These query string arguments are then processed by the Login server if the user is redirected, and qualify 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. Do not call LoginUser from within any framed page. If LoginUser is called from within a frameset and is viewed by a client application that is not .NET Passport-aware, the end user will get a run-time error thrown by the browser scripting engine due to cross frame scripting security issues.

Calling LoginUser while the Passport Manager object is configured in stand-alone mode takes the user to the configured DisasterURL, if any.

Most input parameters of this method can be specified as default values stored in the registry, such that a call could leave most input parameters blank and revert to the registry default values. If values are given for any parameter in a specific method call, the input parameters will override the default values. Use the Passport Manager Administration utility to check or set defaults for returnUrl, TimeWindow, ForceLogin, coBrandArgs or lang_id.

See Also

IPassportManager2 Interface | IPassportManager3::GetLoginChallenge | IPassportManager2::AuthURL2 | Passport Manager Administration Utility