Authentication with Multiple Known Headers

The HTTP_MULTIPLE_KNOWN_HEADERS structure enables server applications to send multiple authentication challenges to the client. Applications can challenge the client with a single authentication scheme by supplying the HttpHeaderWwwAuthenticate enumeration type in the KnownHeaders member of the HTTP_RESPONSE_HEADERS structure contained in HTTP_RESPONSE. However, when the server challenges with multiple authentication schemes, the application uses the HTTP_MULTIPLE_KNOWN_HEADERS structure to provide the authentication types.

When the HTTP_RESPONSE_INFO_FLAGS_PRESERVE_ORDER flag is present, HTTP sends the authentication headers in the specified order. If the flag is not present, HTTP orders the authentication schemes from strongest to weakest as follows:

1. Negotiate
2. NTLM
3. Digest
4. Basic

If the authentication scheme is not one of these schemes, the application must specify the HTTP_RESPONSE_INFO_FLAGS_PRESERVE_ORDER flag.

The KnownHeader member of HTTP_MULTIPLE_KNOWN_HEADERS points to an array of HTTP_KNOWN_HEADER structures. The pRawValue member of the HTTP_KNOWN_HEADER structure must point to a string that specifies the scheme name. HTTP parses the string to determine the scheme and performs one of the following actions:

• If the string contains an unknown authentication type, or if the authentication type is not enabled on the configuration group (either the URL group or server session) associated with the request, the HTTP Server API appends the string in pRawValue to the WWW-Authenticate header. For example, if the application specifies an unsupported authentication scheme, and pRawValue contains the string "CustomAuthString", the following text is appended to the authentication header:

  WWW-Authenticate: CustomAuthSchemeCRLF

  If the application does not have Basic authentication enabled, and pRawValue contains the string "Basic realm="BasicRealm"", the authentication header contains the following text:

  WWW-Authenticate: Basic realm="BasicRealm"

• If the string contains a known authentication type and is present on the configuration group (either the URL group or the server session) associated with the request, the HTTP Server API generates the WWW-Authenticate header. For example if the string specified in pRawValue is "Digest", and Digest is enabled on the server session, the HTTP Server API appends the following text to the authentication header:

  WWW-Authenticate: Digest realm="testrealm@host.com"

If the scheme in the pRawValue member of HTTP_KNOWN_HEADER is Negotiate or NTLM, the authentication scheme name is sufficient. If the specified scheme is Basic, the realm name is appended to the scheme name; the application doesn't need to supply the realm name in pRawValue. If the specified scheme is Digest, HTTP calls AcceptSecurityContext to generate the challenge that is appended to the scheme name. The parameters for Basic (realm) and Digest (realm and domain name) scheme are obtained from the corresponding configuration group authentication information.

When the application sends multiple authentication challenges to the client in Unknown request headers, the HTTP Server API sends these to the client without intervention. However this usage is not recommended.