Share via

IPassportManager::IsAuthenticated

  • Article

IPassportManager::IsAuthenticated

Gets a value indicating whether the user is authenticated against a Microsoft® .NET Passport Login server. This method determines if the current user is authenticated based on the TimeWindow and the ForceLogin parameters.

Syntax

HRESULT IsAuthenticated  (
    VARIANT TimeWindow,
    VARIANT ForceLogin,
    VARIANT SecureLevel,
    VARIANT_BOOL* pVal
);

Parameters

  • 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.
  • SecureLevel
    [in, optional] A VARIANT (VT_INT) value. Enables checking from a Secure Sockets Layer (SSL) sign-in.
  • pVal
    [out, retval] A pointer to a VARIANT Boolean value. Returns VARIANT_TRUE if the connecting user has been signed in to the calling domain within the time specified by TimeWindow. If ForceLogin was set to VARIANT_TRUE, then the user must also have given password within the time specified by TimeWindow. All other cases return VARIANT_FALSE.

Return values

Returns one of the following values:

S_OK Success. If no Ticket is present, still returns S_OK as HRESULT and returns VARIANT_FALSE to pVal.
PP_E_NOT_CONFIGURED Passport Manager registry defaults 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 Supplied arguments were of the wrong type.

Counters

For more information, see Performance Counters.

  • Each call to IPassportManager::IsAuthenticated increments the Total Requests counter.
  • Each call to IPassportManager::IsAuthenticated where pVal returned VARIANT_TRUE increments the Total Successful Auths counter.
  • Each call to IPassportManager::IsAuthenticated where pVal returned VARIANT_FALSE increments the Total Failed Auths counter.
  • Each call to IPassportManager::IsAuthenticated that failed specifically because ForceLogin was set to VARIANT_TRUE (users had Ticket that would have generated a silent refresh except that they were blocked by the ForceSignin requirement) increments the Total Forced SignIns counter.

Remarks

A read-only property. Detects the presence of a valid Ticket cookie in the caller's domain or a fresh Ticket on the query string.

If the optional TimeWindow parameter is omitted, the default TimeWindow specified in the registry is used. Use the Passport Manager Administration utility to set the default TimeWindow.

If the optional ForceLogin parameter is omitted, the default ForceLogin specified in the registry is used. Use the Passport Manager Administration utility to set the default ForceLogin.

If the optional SecureLevel parameter is omitted, the default SecureLevel specified in the registry is used. SecureLevel can be set to the following values:

SecureLevel value Description
0 (or unspecified) Any type of sign-in is acceptable, so long as it passes TimeWindow and/or ForceLogin specified in this method call.
10 Specifying 10 for SecureLevel requires that the last sign-in is made over a secure channel (as enabled by specifying SecureLevel=10 in a call to IPassportManager::AuthURL, IPassportManager2::AuthURL2, or IPassportManager2::LoginUser). Such a sign-in must also pass any additional TimeWindow and/or ForceLogin specified in this method call. Failure to meet these conditions results in pVal returning VARIANT_FALSE.
100 Specifying 100 for SecureLevel requires that the last sign-in is made over a secure channel, and with submission of a security key in addition to password (as enabled by specifying SecureLevel=100 in a call to IPassportManager::AuthURL, IPassportManager2::AuthURL2, or IPassportManager2::LoginUser). Such a sign-in must also pass any additional TimeWindow and/or ForceLogin specified in this method call. Failure to meet these conditions results in pVal returning VARIANT_FALSE.

All input parameters of IPassportManager::IsAuthenticated can be specified globally as default values stored in the registry, such that a call to IPassportManager::IsAuthenticated could leave all input parameters blank and revert to the registry default values. If values are given for any parameter, 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, or lang_id.

If the Passport Manager object is configured to be in stand-alone mode, any valid Ticket in the calling domain is accepted as sign-in credentials, regardless of the Ticket's timestamps and TimeWindow parameter value. However, IPassportManager::IsAuthenticated still returns VARIANT_FALSE if no Ticket is present.

See Also

IPassportManager Interface | IPassportManager2::LogoTag2 | IPassportManager2::AuthURL2 | IPassportManager2::LoginUser | Passport Manager Administration Utility | Stand-Alone Mode