[Breaking change] Make managed NTLM authentication opt-in in .NET 12 #136174

Summary

For .NET 12, make the managed NTLM authentication implementation disabled by default and require applications that still need it for legacy compatibility to explicitly opt in with the existing System.Net.Security.UseManagedNtlm AppContext switch.

This is a behavioral breaking change, not a proposal to remove the implementation or add a new public API.

Related documentation work: #136154.

Motivation

NTLM is a legacy authentication protocol and should not be selected implicitly by the managed implementation. Applications should migrate to Kerberos or another modern authentication mechanism rather than acquire an NTLM dependency through automatic fallback.

This follows the Windows direction:

• Advancing Windows security: Disabling NTLM by default — Windows IT Pro Blog describes the phased roadmap toward an NTLM-independent Windows future.
• Deprecated features in the Windows client lists all versions of NTLM, including NTLMv2, as deprecated since June 2024.
• Features and functionality removed in Windows client confirms that NTLMv1 was removed starting with Windows 11, version 24H2 and Windows Server 2025.

The distinction matters: removal of NTLMv1 does not mean that all NTLM versions have already been removed from Windows. The broader NTLM deprecation and default-disablement direction motivate changing the .NET managed implementation default as well.

Current behavior

The existing switch does not currently provide a consistent opt-in boundary:

• LocalAppContextSwitches.UseManagedNtlm defaults to true on macOS, iOS, Mac Catalyst, OpenBSD, and Linux with a linux-bionic- runtime identifier. It defaults to false elsewhere on the Unix PAL path.
• When enabled, the Unix PAL selects managed NTLM for an explicit NTLM package and managed SPNEGO for Negotiate, allowing NTLM fallback.
• Android and tvOS select the managed-only PAL through project build conditions. That PAL currently creates managed NTLM/SPNEGO without checking the AppContext switch.

Proposed .NET 12 behavior

• Default System.Net.Security.UseManagedNtlm to false on every platform that supports the managed implementation.
• Require an explicit true value before using managed NTLM, both when Package = "NTLM" is requested and when NTLM would be selected through Negotiate/managed SPNEGO.
• Apply the same gate to the managed-only Android/tvOS path; changing only the Unix switch default is insufficient.
• Preserve native Kerberos authentication where available. Do not silently re-enable managed NTLM when Kerberos or native authentication is unavailable; surface the existing appropriate authentication failure/unsupported result.
• Preserve explicit opt-in as a compatibility escape hatch for applications that cannot yet migrate.

This issue is specifically about the managed NTLM implementation. The switch is not a global NTLM prohibition: Windows SSPI and native GSSAPI providers can still support or select NTLM according to their own configuration and operating-system policy. Changing those native-provider policies is outside this issue.

Breaking-change impact and migration

Applications that currently depend on managed NTLM being enabled implicitly can fail authentication after upgrading to .NET 12. This includes callers of NegotiateAuthentication and higher-level consumers such as NegotiateStream and HttpClient when they reach the managed authentication implementation.

Preferred migration: use Kerberos or another modern authentication protocol. Where supported, explicitly requesting Kerberos prevents NTLM selection; Negotiate alone is not a guarantee that NTLM will never be used.

For temporary legacy compatibility, explicitly enable the existing switch before authentication is initialized:

AppContext.SetSwitch("System.Net.Security.UseManagedNtlm", true);

Or configure it in the application runtime configuration:

{
  "runtimeOptions": {
    "configProperties": {
      "System.Net.Security.UseManagedNtlm": true
    }
  }
}

Opting in does not restore NTLM support on a remote server or override Windows policies that disable it.

Acceptance criteria

• With the switch unset or explicitly false, no supported platform uses managed NTLM, either directly or through managed SPNEGO fallback.
• Explicit true preserves supported managed NTLM compatibility scenarios.
• Tests cover unset/false/true, explicit NTLM and Negotiate fallback, and both Unix and managed-only platform paths.
• Native Kerberos scenarios remain functional; the managed switch is not documented as blocking native NTLM.
• Publish .NET 12 breaking-change documentation describing affected platforms, authentication failures, preferred migration, and the compatibility switch; update switch/authentication documentation accordingly.