Share via

IPassportManager2::AuthURL2

  • Article

IPassportManager2::AuthURL2

Returns a string containing the Login server URL for a user's domain, as well as optional information sent to the Login server in the query string.

Important  This method takes advantage of the Microsoft® .NET Passport authentication capabilities that are built into Microsoft® Windows® XP. If you use this method to generate a link to the Login server, users who are using Microsoft® Internet Explorer 6 on Windows XP will enter their credentials into the .NET Passport sign-in user interface (UI) that is integrated into the operating system. As a result, any customized cobranding you supply will not be displayed. If you want to ensure that all users sign in using the cobranding-enabled Web UI, use the AuthURL method of the IPassportManager interface. For more information, see IPassportManager::AuthURL.

Syntax

HRESULT AuthURL2(
  VARIANT returnUrl,
  VARIANT TimeWindow,
  VARIANT ForceLogin,
  VARIANT coBrandArgs,
  VARIANT lang_id,
  VARIANT NameSpace,
  VARIANT KPP, 
  VARIANT SecureLevel, 
  BSTR* pAuthVal
);

Parameters

  • returnUrl
    [in, optional] A VARIANT (should be VT_BSTR) that sets the URL of the location that the Login server should redirect to after sign-in is complete. The return URL to which to return the user upon a successful sign-in or sign-out. Pass a null reference to indicate that .NET Passport should use the default value specified in the application. The return URL must be fully qualified and point to a named file, not just a root. If SecureLevel is set to true, this returnUrl must be an HTTPS URL. Using the Server.URLEncode method, always URL-encode the string. (See IServer::URLEncode in IIS reference.)
  • TimeWindow
    [in, optional] A VARIANT (should be VT_I4) that represents a time value, in seconds. Specifies the interval during which users must have last signed in to the calling domain. The value entered for TimeWindow must be greater than or equal to 20 and less than 2678400 (between 20 seconds and 31 days).
  • ForceLogin
    [in, optional] A VARIANT (should be VT_BOOL) qualifying behavior at the Login server. Determines how the TimeWindow parameter gets used. If set to VARIANT_TRUE, the Login server will compare TimeWindow interval 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) that specifies variables to be appended to the URL of the cobranding template script page that was specified at initial registration. Using the Server.URLEncode method, always URL-encode the entire string. (See IServer::URLEncode in IIS reference.) If left blank, 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 to modify cobranding at run time, see .NET Passport Cobranding Overview.
  • 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.
  • NameSpace
    [in, optional] A VARIANT (VT_BSTR); A namespace to which a user without a .NET Passport is directed by the Login server. Pass null to indicate that .NET Passport should use the default value. 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".
  • KPP
    [in, optional] A VARIANT (VT_I4). Use only if implementing Microsoft® Kids Passport; 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.
  • pAuthVal
    [out, retval] A pointer to a BSTR containing 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. Do not attempt to append query string information or other characters to the URL returned by IPassportManager2::AuthURL2.

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 given was less than 20 or greater than 2678400.
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.

Example

The following C++ example uses the AuthURL2 method to display the Login server URL for a user's domain.

#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;
 //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_IPassportManager, (void**)&piMgr);
 IUnknown* pII_IPassportManager3;
 piMgr->QueryInterface(IID_IPassportManager3, (void**)&pII_IPassportManager3);

 //Login the user.
 piMgr->LoginUser();
 CComVariant returnUrl;
 returnUrl = "https://localhost/Brief";
 CComVariant TimeWindow = 3600;
 CComVariant ForceLogin = -1;
 CComVariant coBrandTemplate = NULL;
 CComVariant lang_id = 1033;
 CComVariant Namespace = -1;
 CComVariant KPP = 0;
 CComVariant SecureLevel = -1;
 CComVariant ExtraParams = NULL;

 //Get AuthURL2
 BSTR pAuthValue;
 hr = piMgr->AuthURL2(
  returnUrl,
  TimeWindow,
  ForceLogin,
  coBrandArgs,
  lang_id,
  Namespace,
  KPP,
  SecureLevel,
  &pAuthValue);
 Console::Write("AuthURL2 = ");
 Console::WriteLine(pAuthValue);

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

Remarks

Participating sites should always inform first-time visitors that they are about to sign in to the .NET Passport network. Do not redirect (using the Response.Redirect method) directly to the Login server URL without first informing the user that he or she is signing in. Otherwise, a silent sign-in can occur without users ever knowing that they have consented to give your site profile information. Participating sites must present a Consent page or equivalent UI at least once to any new visitor so that the purpose and process of signing in to .NET Passport can be explained to the user. Alternatively, use the LogoTag2 link on any page that requires .NET Passport single sign-in (SSI).

Do Not Load Login Server URL in a Frameset

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.

Using Default Values from Passport Manager Object Registry Keys

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

Timestamps and International Considerations

Any request from a Passport Manager object to the Login server includes the local (server clock) time on the incoming query string. New timestamps are established relative to that local time. The local time is established after the page is rendered. The exact time that a user actually clicks the link cannot be determined through .NET Passport methods.

IPassportManager2::AuthURL2 and Stand-Alone Mode

IPassportManager2::AuthURL2 will return the Disaster URL while Passport Manager is in stand-alone mode.

See Also

IPassportManager2 Interface | Passport Manager Administration Utility