WPX_HTTP_FILTER_AUTH_COMPLETE_INFO structure

Applies to: desktop apps only

The Forefront TMG Web proxy includes a pointer to the WPX_HTTP_FILTER_AUTH_COMPLETE_INFO structure in the notification that it sends to Web filters after it has successfully completed authentication. If your filter should be notified for this event, it must register to receive SF_NOTIFY_AUTH_COMPLETE notifications. For more information about the types of event notifications that are sent to Web filters, see Event Notifications.

Syntax

typedef struct WPX_HTTP_FILTER_AUTH_COMPLETE_INFO {
  BOOL (WINAPI) *GetHeader;
  BOOL (WINAPI) *SetHeader;
  BOOL (WINAPI) *AddHeader;
  BOOL (WINAPI) *GetUserToken;
  DWORD         HttpStatus;
  BOOL          fResetAuth;
  DWORD         dwReserved;
  BOOL (WINAPI) *SetUserCachingKey;
} WPX_HTTP_FILTER_AUTH_COMPLETE_INFO;

Members

  • GetHeader
    Pointer to the GetHeader callback function, which can be used to retrieve a specified header or a portion of the request line in the incoming request. Header names include a trailing colon (:). Individual portions of the request line are specified by the special values "method", "URL", and "version". The special values are case-sensitive and must not include the trailing colon.

  • SetHeader
    Pointer to the SetHeader callback function, which can be used to modify or delete the value of a header or to add a new header. This function cannot be used to modify the portions of the request line specified by the special values.

  • AddHeader
    Pointer to the AddHeader callback function, which can be used to add an HTTP header to the request.

  • GetUserToken
    Points to the GetUserToken function that returns a handle to the token of the user for whom impersonation will be performed.

  • HttpStatus
    Not used.

  • fResetAuth
    If set to TRUE, the authentication process will be reset, and no impersonation will be done.

  • dwReserved
    A DWORD reserved for later use.

  • SetUserCachingKey
    Sets the user caching key.

Remarks

This structure allows you to view the method, URL, version, or headers, or to modify the headers sent from the client. It also allows you to set the caching key for this request. You can use this to provide a different caching key for each user.

The SF_NOTIFY_AUTH_COMPLETE notification is sent after the client's identity has been negotiated with the client, or when the client is anonymous. Because of the timing of this notification, the AUTH_USER server variable can be used to reliably obtain the identity of the user. Also, functionality is provided to retrieve a copy of the token that Forefront TMG will use to impersonate the client when processing the request.

All authentication scheme processes should result in either SF_NOTIFY_AUTH_COMPLETE, authentication, giving the filter a handle to a token of the user to be impersonated, or ACCESS_DENIED, when the user is not recognized by the system.

The SF_NOTIFY_AUTH_COMPLETE notification may be used for:

  • Accessing the user token of the user to be impersonated.
  • Actions that can be done in PREPROC_HEADERS, such as GET/ADD or SET request headers.
  • Resetting authentication.

Note  If a filter needs to add Authorization headers after a request is authenticated and before the request is sent to the upstream proxy server or Web server, it must do so by parsing the request in the SF_NOTIFY_FORWARD_RAW_DATA notification, rather than in the SF_NOTIFY_AUTH_COMPLETE notification.

This is because when the request is authenticated, Forefront TMG removes every Authorization header before sending the request on to the upstream proxy server or Web server. (In forward-proxy scenarios, it removes Proxy-Authorization headers. In reverse-proxy scenarios, it removes Authorization headers.) Therefore, even if the filter adds an Authorization header after receiving the SF_NOTIFY_AUTH_COMPLETE notification, it will be removed.

Requirements

Minimum supported client

None supported

Minimum supported server

Windows Server 2008 R2, Windows Server 2008 with SP2 (64-bit only)

Version

Forefront Threat Management Gateway (TMG) 2010

Header

Wpxhttpfilt.h

See also

Notification Structures

 

 

Build date: 7/12/2010