Share via

IPassportManager3::GetLoginChallenge

  • Article

IPassportManager3::GetLoginChallenge

Returns URL and header information to facilitate a Microsoft® .NET Passport sign-in. This method supports .NET Passport-aware client applications and the Credentials Manager used in the Microsoft® Windows® XP operating system.

Syntax

HRESULT GetLoginChallenge(
  VARIANT returnUrl,
  VARIANT TimeWindow,
  VARIANT ForceLogin,
  VARIANT coBrandArgs,
  VARIANT lang_id,
  VARIANT NameSpace,
  VARIANT KPP,
  VARIANT SecureLevel,
  VARIANT ExtraParams,
  BSTR *pAuthHeader, 
 );

Parameters

  • returnUrl
    [in, optional] A VARIANT (should be VT_BSTR) that specifies the URL to which the Login server should redirect users after sign-in is complete. Pass a null reference to indicate that .NET Passport should use the return URL value specified in the Passport Manager Administration utility. The return URL must be fully qualified and point to a named file, not just a root.
  • TimeWindow
    [in, optional] A VARIANT (should be VT_I4) that specifies the interval, in seconds, during which users must have last signed in to the calling domain. The value entered for TimeWindow must be -1, greater than or equal to 20, and less than 2678400 (between 20 seconds and 31 days). The TimeWindow parameter is used in conjunction with the ForceLogin parameter. Pass -1 to indicate that .NET Passport should use the default value specified in the Passport Manager Administration utility.
  • ForceLogin
    [in, optional] A VARIANT (should be VT_BOOL). If set to VARIANT_TRUE, the Login server compares TimeWindow against the time since the user last manually signed in. If set to VARIANT_FALSE, then the Login server will compare TimeWindow against the last time the Ticket was refreshed either silently or manually.
  • coBrandArgs
    [in, optional] A VARIANT (should be (VT_BSTR). A string specifying variables to be appended as query string variables to the URL of the participating site's cobranding template script page. Pass a null reference to indicate that .NET Passport should use the Cobrand Args value specified in the Passport Manager Administration utility.
  • lang_id
    [in, optional] A VARIANT (should be VT_I4). Specifies the language to be used for the Sign-in page that is displayed to the user. Pass -1 to indicate that .NET Passport should use the default value specified in the Passport Manager Administration utility.
  • NameSpace
    [in, optional] A VARIANT (VT_BSTR); A domain namespace to which you want to direct users without .NET Passports to register. The specified namespace must appear as a "domain name" entry in the Partner.xml Component Configuration Document (CCD). The typical default namespace is "passport.com". Pass a null reference to indicate that .NET Passport should use the default value.
  • KPP
    [in, optional] A VARIANT (VT_I4). Use only if implementing the Microsoft® Kids Passport service; otherwise, leave blank. By setting KPP to different levels on a per-page basis, a site can allow or deny access to children only where strictly necessary. Pass -1 to indicate that .NET Passport should use the default value.
  • SecureLevel
    [in, optional] A VARIANT (should be VT_INT). Enables checking for a Login from a Secure Sockets Layer (SSL) sign-in.
  • ExtraParams
    [in, optional] A VARIANT (should be VT_BSTR). Declares whether the actual sign-in user interface (UI) should be served HTTPS from the .NET Passport domain authority. Use 0 for false, 1 for true, and -1 to indicate that .NET Passport should use the default value.
  • pAuthHeader
    [out, retval] A pointer to a BSTR containing the headers that should be included in the request to the .NET Passport Login server. The headers are contained in a single VARIANT of type VT_BSTR, potentially with \n or other breaks within the string to differentiate the header elements. This includes the headers that are specific for the interaction of a .NET Passport-aware client application. Append these headers along with any custom headers that you wish to submit, and write all of these into an appropriate redirect to the Login server URL that is then sent to the requesting client.

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 the 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 can 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 whether invalid values came from a specific call or from registry defaults.

Example

The following C++ example retrieves and displays the GetLoginChallenge method. The retval is subsequently displayed.

#include "stdafx.h"
#include <atlbase.h>
#using <mscorlib.dll>
#import "C:/WINNT/system32/MicrosoftPassport/msppmgr.dll" named_guids raw_interfaces_only no_namespace
using namespace System;

// This is the entry point for this application.
int _tmain(void)
{
HRESULT hr;
IPassportManager3* piMgr = NULL;
//Initialize the COM library and retrieve a pointer
//to an IID_IPassportManager interface.
hr = CoInitialize(NULL);
hr = CoCreateInstance(CLSID_Manager, NULL, CLSCTX_INPROC_SERVER, IID_IPassportManager3, (void**)&piMgr);
IUnknown* pII_IPassportManager3;
piMgr->QueryInterface(IID_IPassportManager3, (void**)&pII_IPassportManager3);

CComVariant returnUrl;
returnUrl = "https://localhost/Brief";
CComVariant TimeWindow = 3600;
CComVariant ForceLogin = true;
CComVariant coBrandArgs = NULL;
CComVariant lang_id = 1033;
CComVariant Namespace = NULL;
CComVariant KPP = -1;
CComVariant SecureLevel = -1;
CComVariant ExtraParams = NULL;

BSTR pAuthHeader;
 piMgr->GetLoginChallenge(
 returnUrl,
 TimeWindow,
 ForceLogin,
 coBrandArgs,
 lang_id,
 Namespace,
 KPP,
 SecureLevel,
 ExtraParams,
 &pAuthHeader);
Console::Write("GetLoginChallenge: ");
Console::WriteLine(pAuthHeader);

//cleanup
hr = piMgr->Release();
CoUninitialize();
}

The preceding example results in an page that looks like the following: 

GetLoginChallenge: Passport1.4 lc=1033,id=23248,tw=3600,fs=1,ru=https://localhost
/Brief,ct=1026252457,kv=1,ver=2.1.0191.1,seclog=10,tpf=801b717c30652dfecf17f2c4
30543d4,0

Remarks

The lang_id is an integer representation of a standard locale ID (LCID). For example, U.S. English (EN/US) is 1033.

The returned response header field contains the URL of the calling page, plus a query string parameter containing the .NET Passport Login server with other parameters in the encoded query string. These query string arguments are then processed by the Login server if the user is redirected, and determine whether the Login server can refresh credentials silently or must display the Login form.

If the .NET Passport user's client is determined to not be inherently .NET Passport aware, all authorization interactions default to the mechanisms used in previous releases. The URL in this case is simply the .NET Passport Login server URL with appropriate query string. This sequence requires that the MSPPFLTR.DLL be installed and running as an ISAPI filter at the global level of the participating Web site.

If the client is determined to be .NET Passport aware, 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. However, the URL is returned as a string for purposes of servers or applications that also wish to insert additional information into the HTTP headers and thus wish to initiate their own redirect. Such servers should redirect clients to the URL returned by this method, to facilitate .NET Passport sign-in.

If the optional SecureLevel parameter is omitted, the default SecureLevel value of 0 is used. SecureLevel can be set to the following values:

SecureLevel value Description
0 (or unspecified) The sign-in UI is served by HTTP protocol 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 the persistent sign-in option.
10 The 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 The sign-in UI is served HTTPS from the .NET Passport domain authority, and the sign-in process now requires submission of a security key in addition to password. For more information, see SSL Sign-In.

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

Do not load the Login server URL in a frame set. Because of security concerns, the .NET Passport Login server URL cannot be loaded into a frame set; it must always be the top window in the object model. Do not call GetLoginChallenge from within any framed page. If GetLoginChallenge is called from within a frame set and is viewed by a client application that is not .NET Passport-aware, the user will get a run-time error generated by the browser scripting engine (due to cross-frame scripting security issues).

Calling GetLoginChallenge while the Passport Manager object is configured 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.

Most input parameters of this method can be specified as default values stored in the registry, so that a call can 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 given parameters override the default values. Use the Passport Manager Administration utility to check or set defaults for returnUrl, TimeWindow, ForceLogin, coBrandArgs, and lang_id.

See Also

Passport Manager Administration Utility