http.sys: Allow configuring extended authentication flags (HTTP_AUTH_EX_FLAG) as options
- Dominant language
- C#
- Stars
- 38.4k
- Forks
- 10.9k
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 281
Description
## Background and Motivation
The native HTTP.sys API offers two extended authentication flags:
- [`HTTP_AUTH_EX_FLAG_ENABLE_KERBEROS_CREDENTIAL_CACHING`](https://learn.microsoft.com/en-us/windows/win32/api/http/ns-http-http_server_authentication_info) and
- [`HTTP_AUTH_EX_FLAG_CAPTURE_CREDENTIAL`](https://learn.microsoft.com/en-us/windows/win32/api/http/ns-http-http_server_authentication_info)
that can be used by users to fine-tune their Windows authentication setups:
For instance, the `HTTP_AUTH_EX_FLAG_ENABLE_KERBEROS_CREDENTIAL_CACHING` flag can be used to avoid having to authenticate every request and make the authentication session-based, thus reducing the overall number of requests and improving the high-latency scenarios. Enabling it can be used to achieve the same behavior as with the [`authPersistNonNTLM` option in IIS](https://techcommunity.microsoft.com/t5/iis-support-blog/kerberos-authpersistnonntlm-authentication-request-based-vs/ba-p/324663).
This proposal exposes this part of the stable Win32 HTTP Server API as configuration options of the `HttpSys` server.
See #51833 for additional details.
See #13634 for a usage example.
## Proposed API
```diff
namespace Microsoft.AspNetCore.Server.HttpSys;
public sealed class AuthenticationManager
{
+ ///
+ /// If true, the Kerberos authentication credentials are persisted per connection
+ /// and re-used for subsequent anonymous requests on the same connection.
+ /// Kerberos or Negotiate authentication must be enabled. The default is false.
+ ///
+ public bool EnableKerberosCredentialCaching { get; set; }
+ ///
+ /// If true, the server captures the caller's credentials and uses them for Kerberos
+ /// or Negotiate authentication. Kerberos or Negotiate authentication must be enabled.
+ /// The default is false.
+ ///
+ public bool CaptureCredentials { get; set; }
}
```
## Usage Examples
```csharp
webBuilder.UseHttpSys(options =>
{
options.Authentication.Schemes = AuthenticationSchemes.Negotiate;
options.Authentication.EnableKerberosCredentialCaching = true;
});
```
## Alternative Designs
1. Potentially, these options could've been expressed as a single enum `[Flags]` property.
However, the existing properties in `AuthenticationManager` tend to use `bool` properties for similar configuration settings ([`bool AllowAnonymous`](https://github.com/dotnet/aspnetcore/blob/8a539d35e7db61ce0956489f60edaa4ac0c57ce6/src/Servers/HttpSys/src/AuthenticationManager.cs#L49), [`bool AutomaticAuthentication`](https://github.com/dotnet/aspnetcore/blob/8a539d35e7db61ce0956489f60edaa4ac0c57ce6/src/Servers/HttpSys/src/AuthenticationManager.cs#L59)).
Also, the `ExFlags` field in the native `HTTP_SERVER_AUTHENTICATION_INFO` structure seems to exist for a historical reason — presumably, to pack multiple new values into a single available byte, because older similar fields are bool-typed.
2. There are possible naming variations for the new boolean options.
The currently selected naming scheme fully mirrors the names of the corresponding flags from the native API (such as `HTTP_AUTH_EX_FLAG_ENABLE_KERBEROS_CREDENTIAL_CACHING`), to avoid any unintended semantic changes.
## Risks
None that I'm aware of: new options mirror an existing stable Win32 HTTP Server API.
Contributor guide
Assessment
This issue has not been assessed yet.