dotnet / dotnet/aspnetcore

http.sys: Allow configuring extended authentication flags (HTTP_AUTH_EX_FLAG) as options

Open
#51,990 9 comments 0 reactions 0 assignees View on GitHub
api-approved area-networking feature-httpsys
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.