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

[evgenykotkov]

Background and Motivation

The native HTTP.sys API offers two extended authentication flags:

• HTTP_AUTH_EX_FLAG_ENABLE_KERBEROS_CREDENTIAL_CACHING and
• HTTP_AUTH_EX_FLAG_CAPTURE_CREDENTIAL

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.

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

namespace Microsoft.AspNetCore.Server.HttpSys;

public sealed class AuthenticationManager
{
+    /// <summary>
+    /// 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.
+    /// </summary>
+    public bool EnableKerberosCredentialCaching { get; set; }

+    /// <summary>
+    /// 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.
+    /// </summary>
+    public bool CaptureCredentials { get; set; }
}

Usage Examples

    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, bool AutomaticAuthentication).

   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.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[halter73]

API Review Notes:

• @Tratcher asked "Who's credentials? CaptureCredentials -> CaptureProcessCredentials or UseProcessCredentials."
• Given that the native flag names, boolean EnableKerberosCredentialCaching and CaptureProcessCredentials properties on HttpSysOptions.Authentication are a good way to translate it to .NET. We could consider using a flags enum like the native API, but we don't see the need to define new types to configure two independent boolean options.

API Approved!

namespace Microsoft.AspNetCore.Server.HttpSys;

public sealed class AuthenticationManager
{
+    public bool EnableKerberosCredentialCaching { get; set; }
+    public bool CaptureProcessCredentials { get; set; }
}

Edit: An updated API was approved here

[evgenykotkov]

@halter73 @Tratcher

Thank you for the API review!

I would like to point out one potential issue with the suggested CaptureProcessCredentials name.

Based on my current understanding, the captured credentials (which are then impersonated during a call to AcquireCredentialsHandle() in http.sys) aren't necessarily the process credentials, but rather are the credentials of the caller who modifies the authentication property. So if this happens from a thread with a custom security context, the captured credentials will be from that thread, and not from the process.

My original idea was to keep the same name as in the native flag (HTTP_AUTH_EX_FLAG_CAPTURE_CREDENTIAL), because it guarantees that no unintended semantic changes are going to happen. However, if using the CaptureCredentials name is unacceptable, a few possible alternatives would be to name it CaptureCallerCredentials or CaptureCurrentCredentials.

What do you think?

[halter73]

So if this happens from a thread with a custom security context, the captured credentials will be from that thread, and not from the process.

The problem with names like CaptureCallerCredentials or CaptureCurrentCredentials, is that is the "caller" or "current" credentials are that of the host and not that of the AuthenticationManager property setter whatever we decide to call it.

I suppose we could call it CaptureThreadCredentialsDuringHostStartup, but that's a little wordy. Do expect people who will set this property to true often will create a thread with a custom security context to start the host? Or do you think the common case is that they want to use the credentials of the user who launched the process?

I think doc comments can clarify that "process" credentials in this case specifically refers to the credentials of the thread that started the host and maps directly to the native HTTP_AUTH_EX_FLAG_CAPTURE_CREDENTIAL flag.

I don't think it's a good idea to call it CaptureCredentials even if it lines up better with the native API, because I suspect that many customers might assume HttpSysOptions.Authentication.CaptureCredentials to refer to something related to connection level negotiate/kerberos/ntlm auth and naively set it to true without realizing the implications.

[Tratcher]

99.99% of the time it will be the process credentials. There's little reason for anyone to change the current thread credentials, especially during startup.