Docs for new Negotiate auth handler #12420

Author: Tratcher

aspnetcore/security/authentication/windowsauth.md

@@ -12,10 +12,23 @@ uid: security/authentication/windowsauth
 
 By [Scott Addie](https://twitter.com/Scott_Addie) and [Luke Latham](https://github.com/guardrex)
 
-[Windows Authentication](/iis/configuration/system.webServer/security/authentication/windowsAuthentication/) can be configured for ASP.NET Core apps hosted with [IIS](xref:host-and-deploy/iis/index) or [HTTP.sys](xref:fundamentals/servers/httpsys).
+::: moniker range=">= aspnetcore-3.0"
+
+Windows Authentication (A.K.A. Negotiate, Kerberos, or NTLM) can be configured for ASP.NET Core apps hosted with [IIS](xref:host-and-deploy/iis/index), [Kestrel](xref:fundamentals/servers/kestrel), or [HTTP.sys](xref:fundamentals/servers/httpsys).
+
+::: moniker-end
+
+::: moniker range="< aspnetcore-3.0"
+
+Windows Authentication (A.K.A. Negotiate, Kerberos, or NTLM) can be configured for ASP.NET Core apps hosted with [IIS](xref:host-and-deploy/iis/index) or [HTTP.sys](xref:fundamentals/servers/httpsys).
+
+::: moniker-end
 
 Windows Authentication relies on the operating system to authenticate users of ASP.NET Core apps. You can use Windows Authentication when your server runs on a corporate network using Active Directory domain identities or Windows accounts to identify users. Windows Authentication is best suited to intranet environments where users, client apps, and web servers belong to the same Windows domain.
 
+> [!NOTE]
+> Windows Authentication is not supported on HTTP/2. These components allow authentication challenges to be sent on HTTP/2 responses and require the client to downgrade to HTTP/1.1 before authenticating.
+
 ## IIS/IIS Express
 
 Add authentication services by invoking <xref:Microsoft.Extensions.DependencyInjection.AuthenticationServiceCollectionExtensions.AddAuthentication*> (<xref:Microsoft.AspNetCore.Server.IISIntegration?displayProperty=fullName> namespace) in `Startup.ConfigureServices`:
@@ -119,9 +132,66 @@ Use **either** of the following approaches:
   * Use IIS Manager to reset the settings in the *web.config* file after the file is overwritten on deployment.
   * Add a *web.config file* to the app locally with the settings.
 
+::: moniker range=">= aspnetcore-3.0"
+
+## Kestrel
+
+ The [Microsoft.AspNetCore.Authentication.Negotiate](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.Negotiate) nuget package can be used with [Kestrel](xref:fundamentals/servers/kestrel) to support Windows authentication using Negotiate, Kerberos, and NTLM on Windows, Linux, and Mac.
+
+> [!WARNING]
+> This component can persist credentials across requests on a given connection and MUST NOT be used with proxies unless they maintain a 1:1 connection affinity. This means it must not be used with Kestrel behind IIS ASP.NET Core Module (ANCM) out-of-proc.
+
+ Add authentication services by invoking <xref:Microsoft.Extensions.DependencyInjection.AuthenticationServiceCollectionExtensions.AddAuthentication*> (<xref:Microsoft.AspNetCore.Authentication.Negotiate?displayProperty=fullName> namespace) and <xref:Microsoft.Extensions.DependencyInjection.AuthenticationServiceCollectionExtensions.AddNegotitate*> (<xref:Microsoft.AspNetCore.Authentication.Negotiate?displayProperty=fullName> namespace) in `Startup.ConfigureServices`:
+
+ ```csharp
+services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
+    .AddNegotiate();
+```
+
+Then add the Authentication [middleware](xref:fundamentals/middleware/index) by calling [UseAuthentication](/dotnet/api/microsoft.aspnetcore.builder.authappbuilderextensions.useauthentication#Microsoft_AspNetCore_Builder_AuthAppBuilderExtensions_UseAuthentication_Microsoft_AspNetCore_Builder_IApplicationBuilder_) in `Startup.Configure`.
+
+ ```csharp
+    app.UseAuthentication();
+
+    app.UseMvc();
+```
+
+Anonymous requests are allowed by this component. Use [Authorization](xref:security/authorization/introduction) to challenge anonymous requests for authentication.
+
+### Environment configuration
+
+Some operating system specific configuration is required.
+
+#### Windows
+
+The [Microsoft.AspNetCore.Authentication.Negotiate](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.Negotiate) component does user mode authentication so on Windows the SPNs must be added to the user account running the service, not the machine account. Call `setspn -S HTTP/mysrevername.mydomain.com myuser` from an admin command prompt.
+
+#### Linux and Mac
+
+Instructions for joining a Linux or Mac machine to a Windows domain can be found at [here](https://docs.microsoft.com/en-us/sql/azure-data-studio/enable-kerberos?view=sql-server-2017#join-your-os-to-the-active-directory-domain-controller). Those instructions create a machine account for the Linux machine on the domain. SPNs will need to be added to that SPN account.
+
+> [!NOTE]
+> The Linux instructions were tested with Ubuntu 18.04 and the install list is outdated. Replace python-software-properties with python3-software-properties if needed.
+
+Once the Linux or Mac machine is joined to the domain a few additional steps are required to provide a keytab file with the SPNs:
+- On the domain controller add new SPNs for the web service to the machine account:
+  - `setspn -S HTTP/mywebservice.mydomain.com mymachine`
+  - `setspn -S HTTP/[email protected] mymachine`
+- Use [ktpass](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/ktpass) to generate a keytab file:
+  - `ktpass -princ HTTP/[email protected] -pass myKeyTabFilePassword -mapuser MYDOMAIN\mymachine$ -pType KRB5_NT_PRINCIPAL -out c:\temp\mymachine.HTTP.keytab -crypto AES256-SHA1`
+  - Some fields must be specified in UPPER CASE as indicated.
+- Copy that keytab file to the linux machine.
+- Select that keytab via environment variable: `export KRB5_KTNAME=/tmp/mymachine.HTTP.keytab`
+- Invoke `klist` to show the SPNs currently available for use.
+
+> [!NOTE]
+> A keytab file contains domain access credentials and should be protected accordingly.
+
+::: moniker-end
+
 ## HTTP.sys
 
-In self-hosted scenarios, [Kestrel](xref:fundamentals/servers/kestrel) doesn't support Windows Authentication, but you can use [HTTP.sys](xref:fundamentals/servers/httpsys).
+[HTTP.sys](xref:fundamentals/servers/httpsys) supports kernel mode Windows authentication using Negotiate, NTLM, or Basic authentication.
 
 Add authentication services by invoking <xref:Microsoft.Extensions.DependencyInjection.AuthenticationServiceCollectionExtensions.AddAuthentication*> (<xref:Microsoft.AspNetCore.Server.HttpSys?displayProperty=fullName> namespace) in `Startup.ConfigureServices`:
 
@@ -172,6 +242,12 @@ ASP.NET Core doesn't implement impersonation. Apps run with the app's identity f
 
 `RunImpersonated` doesn't support asynchronous operations and shouldn't be used for complex scenarios. For example, wrapping entire requests or middleware chains isn't supported or recommended.
 
+::: moniker range=">= aspnetcore-3.0"
+
+While the [Microsoft.AspNetCore.Authentication.Negotiate](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.Negotiate) package enables authentication on Windows, Linux and Mac, impersonation is only supported on Windows.
+
+::: moniker-end
+
 ## Claims transformations
 
 When hosting with IIS in-process mode, <xref:Microsoft.AspNetCore.Authentication.AuthenticationService.AuthenticateAsync*> isn't called internally to initialize a user. Therefore, an <xref:Microsoft.AspNetCore.Authentication.IClaimsTransformation> implementation used to transform claims after every authentication isn't activated by default. For more information and a code example that activates claims transformations when hosting in-process, see <xref:host-and-deploy/aspnet-core-module#in-process-hosting-model>.