Configure Windows Authentication in ASP.NET Core - Kestrel does not include 'UseAuthentication'

[mdell-seradex]

Description

In that article, under the Kestrel section, it says that Authentication is enabled by the following highlighted code.
The highlighted code includes builder.Services.AddAuthentication, builder.Services.AddAuthorization, and app.UseAuthorization.

While app.UseAuthentication is included in the code, it is not highlighted as if it is not required when manually implementing this.
It does not make sense to me that this should be excluded - not highlighted as well - since Authentication is required before Authorization.
Note that it was also excluded from the list of APIs used in the preceding code.
I suspect it was simply missed.

I appreciate any feedback or clarity you can provide.

Thank you
Mark

Page URL

https://learn.microsoft.com/en-us/aspnet/core/security/authentication/windowsauth?view=aspnetcore-8.0&tabs=visual-studio

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/security/authentication/windowsauth.md

Document ID

fbc36c26-9992-1f4c-66d3-02f898ee7ec4

Platform Id

7e670460-f1b6-a509-340f-e6936ea78313

Article author

@wadepickett

Metadata

• ID: 401ad9a0-9e51-80a2-5846-82e9790d7257
• PlatformId: 7e670460-f1b6-a509-340f-e6936ea78313
• Service: aspnet-core
• Sub-service: security

---

Associated WorkItem - 499605

[wadepickett]

@mdell-seradex thanks very much for taking the time to point out this problem in the doc. It does need to be fixed!

[wadepickett]

The following is automated AI analysis to be considered, but reviewed carefully, as this issue is addressed:

Issue Analysis: Missing UseAuthentication Highlight in Windows Authentication Documentation

Issue Summary

This is a valid issue. In the "Kestrel" section of the Windows Authentication documentation, the highlighted code snippet doesn't include app.UseAuthentication() in the highlighted portions, despite this method being crucial for authentication to work properly. The API reference list below the snippet also fails to include the UseAuthentication method.

Note: Calling AddAuthentication() and AddNegotiate() registers and configures the Negotiate handler; it does not run authentication per request. The Authentication middleware (app.UseAuthentication()) invokes the handler and populates HttpContext.User, and must appear before app.UseAuthorization() for policy evaluation to work.

Target Environment

• .NET 6.0 (indicated by the moniker range and code samples)
• Documentation targets multiple environments where ASP.NET Core apps can run (IIS, Kestrel, HTTP.sys)

Affected Files

1. Main documentation file:
   • aspnetcore/security/authentication/windowsauth.md
   • Changes needed on lines 179-187 (Kestrel section)
   • Current highlight parameter on line 181: highlight=1,4-11,27-28
   • Should include line 32 (app.UseAuthentication()) in the highlight

Action Plan

1. Update Lead-in Sentence (line ~179)

Replace:

Authentication is enabled by the following highlighted code to Program.cs:

With:

Authentication and a fallback authorization policy are enabled by the following highlighted code in Program.cs:

2. Update Code Snippet Highlight Parameter (line ~181)

Change from:

[!code-csharp[](windowsauth/6.0samples/WebRPwinAuth/Program.cs?name=snippet1&highlight=1,4-11,27-28)]

To:

[!code-csharp[](windowsauth/6.0samples/WebRPwinAuth/Program.cs?name=snippet1&highlight=1,4-11,13-16,32-33)]

3. Add Explanatory Text After Code Block (after line ~183)

Add:

Highlighted lines:

• 10–11: AddAuthentication + AddNegotiate (register and configure Negotiate authentication)
• 13–16: AddAuthorization with a fallback policy (enforces authenticated users by default)
• 32: app.UseAuthentication() (executes authentication handlers each request; sets HttpContext.User)
• 33: app.UseAuthorization() (evaluates authorization policies, including the fallback)

Note: Merely calling AddAuthentication() and AddNegotiate() registers and configures the Negotiate handler; it does not run authentication per request. The Authentication middleware (app.UseAuthentication()) invokes the handler and populates HttpContext.User, and must appear before app.UseAuthorization() for policy evaluation to work.

4. Update API Reference List (lines ~185-187)

Replace:

The following APIs are used in the preceding code:

• xref:Microsoft.Extensions.DependencyInjection.AuthenticationServiceCollectionExtensions.AddAuthentication%2A
• xref:Microsoft.Extensions.DependencyInjection.NegotiateExtensions.AddNegotiate%2A
• xref:Microsoft.AspNetCore.Builder.AuthAppBuilderExtensions.UseAuthentication%2A

With:

The following APIs are used in the preceding highlighted code:

• xref:Microsoft.Extensions.DependencyInjection.AuthenticationServiceCollectionExtensions.AddAuthentication%2A
• xref:Microsoft.Extensions.DependencyInjection.NegotiateExtensions.AddNegotiate%2A
• xref:Microsoft.Extensions.DependencyInjection.AuthorizationServiceCollectionExtensions.AddAuthorization%2A
• xref:Microsoft.AspNetCore.Builder.AuthAppBuilderExtensions.UseAuthentication%2A
• xref:Microsoft.AspNetCore.Builder.AuthorizationAppBuilderExtensions.UseAuthorization%2A

5. (Optional) Update Template Generated Code Statement (line ~183)

Replace:

The preceding code was generated by the ASP.NET Core Razor Pages template with Windows Authentication specified.

With:

The preceding code (including the fallback authorization policy) was generated by the ASP.NET Core Razor Pages template with Windows Authentication specified.

Implementation Notes

• Verify that snippet1 still contains the lines referenced (10–11, 13–16, 32–33) after any future edits.
• Ensure no other highlight arguments on the page inadvertently imply that UseAuthentication is optional in Kestrel scenarios.
• No code sample changes required - source sample already contains the correct calls and ordering (UseAuthentication precedes UseAuthorization).

Problem Context

The current documentation does not properly highlight the importance of the UseAuthentication middleware. When implementing Windows Authentication with Kestrel, it's crucial to understand that:

1. Service registration (AddAuthentication/AddNegotiate) only configures the services
2. The actual authentication process happens during request processing via the middleware pipeline
3. UseAuthentication middleware must be called to invoke the authentication handlers
4. UseAuthentication must appear before UseAuthorization for proper policy evaluation

The current highlighting in the documentation could mislead developers into thinking that the UseAuthentication middleware call is optional, when in fact it is required for authentication to work properly.

Expected Outcome

After these changes, readers will clearly understand:

• Both service registration AND middleware are required for authentication to work
• The correct order of middleware (UseAuthentication before UseAuthorization)
• The distinct roles of each component in the authentication/authorization process
• The relationship between the fallback policy and the authorization middleware

Analysis completed: 2025-10-17, Wade Pickett + Copilot + Claude Sonnet 3.7 + Repo specific Copilot instruction + Test of Review-Action-Plan AI instruction v9.15.25.2.17.pm