Full review and update: Configure certificate authentication in ASP.NET Core

[wadepickett]

Description

This article has not been fully updated for a few years and could use a thorough review and possible update.

Possible key issue at a glance, but verify:

1. Code samples target net6.0 but should be updated to target net10.0

• The sample project at aspnetcore/security/authentication/certauth/samples/6.x/ targets net6.0 with package version 6.0.1. The article's >= aspnetcore-6.0 moniker pulls snippets exclusively from this 6.x folder. For an article viewed under ?view=aspnetcore-10.0, the samples should be updated to a 10.x sample project (or at minimum 9.x), targeting the current TFM and NuGet package versions.

• The article uses only two moniker ranges: >= aspnetcore-6.0 and >= aspnetcore-5.0 < aspnetcore-6.0. There's no .NET 9+ or .NET 10+ specific, The article should ideally have a modern sample set and acknowledge current framework versions.

3. Outdated API patterns and links

• The RFC link was updated from tools.ietf.org → datatracker.ietf.org (good), but only in the >= 6.0 moniker — the 5.0 moniker still uses the old link.
• The ListenOptions.UseHttps cross-reference link was updated to #configure-https-in-code, which is correct for current docs.
• The netsh docs link was updated — worth verifying the new anchor #parameters is valid.

4. No mention of newer .NET features

• ConfigurePrimaryHttpMessageHandler is deprecated in favor of ConfigurePrimaryHttpMessageHandler() (generic overload) starting in .NET 8+. The article and sample still use the older pattern.
• No mention of the simplified authentication configuration overloads introduced in .NET 9.
• No mention of .NET 10's security CVE fix (CVE-2026-40372) that affected DataProtection/authentication cookies — relevant if cert auth is combined with cookie auth.

See teams light freshenss update thread on Light Freshness Edit: ASP.NET - Config Cert Auth by GitHubber17 · Pull Request #37064 · dotnet/AspN…

Also see #37064. This was a light freshness thread. blowdart indicated it could use a thorogh review and code may be out date.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/security/authentication/certauth?view=aspnetcore-10.0

Content source URL

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

Document ID

d2db534b-198a-dc99-5b5a-0525582d39ac

Platform Id

c04ffbd0-0264-de86-8ac8-5c156c4b4204

Article author

@blowdart

Metadata

• ID: 35b7960d-6de5-78ee-bc45-d7218239bbc8
• PlatformId: c04ffbd0-0264-de86-8ac8-5c156c4b4204
• Service: aspnet-core
• Sub-service: security

Related Issues

[wadepickett]

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution — it is an initial assessment to guide the team's review.

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-04-29
Issue: 37066
Model: GitHub Copilot

📋 Issue Summary

The article "Configure certificate authentication in ASP.NET Core" has not received a thorough update in several years. The only code samples target net6.0 with NuGet package version 6.0.1, there is no 10.x (or even 9.x) sample folder, and the article lacks coverage of newer .NET features and deprecations. Multiple external links also use outdated URLs. A light freshness PR (#37064) was already submitted, but @blowdart indicated a full technical review is needed.

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/security/authentication/certauth.md	1-384	>= aspnetcore-6.0 moniker (entire section)
Project file	certauth/samples/6.x/CertAuthSample/CertAuthSample.csproj	1-13	TFM & package version
Snippets file	certauth/samples/6.x/CertAuthSample/Snippets/Program.cs	174-189	ConfigurePrimaryHttpMessageHandler (deprecated overload)
Validation service	certauth/samples/6.x/CertAuthSample/Snippets/SampleCertificateValidationService.cs	—	Validation sample
Thumbprint validation	certauth/samples/6.x/CertAuthSample/Snippets/SampleCertificateThumbprintsValidationService.cs	—	Thumbprint validation sample
HttpService sample	certauth/samples/6.x/CertAuthSample/Snippets/SampleHttpService.cs	—	HttpClient usage sample
Main Program.cs	certauth/samples/6.x/CertAuthSample/Program.cs	—	Kestrel config sample

Suggested Action Plan

For documentation team review

1. Create new 10.x sample project**

   • Copy the 6.x sample as a starting point into a new 10.x folder
   • Update TFM to net10.0 and NuGet package to the current version
   • Update all deprecated API calls (ConfigurePrimaryHttpMessageHandler → generic overload)
   • Ensure the project compiles and runs

2. Update article moniker references**

   • Point all :::code snippet references in the >= aspnetcore-6.0 moniker to the new 10.x sample folder
   • Add notes for .NET 9+ simplified authentication configuration overloads if applicable

3. Fix all outdated links**

   • tools.ietf.org → datatracker.ietf.org (lines 14, 351, 389)
   • Verify the netsh docs link anchor #parameters is valid

4. Evaluate 5.0 moniker removal**

   • .NET 5 is EOL; consider removing.

5. Verify with dev team

   • Verify CVE-2026-40372 relevance to this article
   • Confirm .NET 9/10 cert auth API changes.

6. Additial checks:

• Verify all changes apply correctly to .NET 10
• Check if the Optional client certificates sample link (line 337, pointing to dotnet/aspnetcore samples) is still valid
• Check if related articles (e.g., proxy/load balancer, Kestrel HTTPS) need corresponding updates
• Consider [!WARNING] block for the deprecated ConfigurePrimaryHttpMessageHandler pattern
• Check if the Optional client certificates sample link (line 337, pointing to dotnet/aspnetcore samples) is still valid
• Check if related articles (e.g., proxy/load balancer, Kestrel HTTPS) need corresponding updates
• Consider [!WARNING] block for the deprecated ConfigurePrimaryHttpMessageHandler pattern

[classyk12]

Might be worth looking into this if no one has picked this up @wadepickett