Code sample for Claims-based authorization violate ASP0025

[abatishchev]

Description

The code samples from https://learn.microsoft.com/en-us/aspnet/core/security/authorization/claims?view=aspnetcore-10.0#adding-claims-checks, namely:

builder.Services.AddAuthorization(options =>
   options.AddPolicy("EmployeeOnly", policy => ...));

violates https://learn.microsoft.com/en-us/aspnet/core/diagnostics/asp0025?view=aspnetcore-10.0 which suggests using this instead:

builder.Services.AddAuthorizationBuilder()
                .AddPolicy("EmployeeOnly", policy => policy => ...);

Page URL

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

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/security/authorization/claims.md

Document ID

50736569-fc04-ec6d-7b33-a3e0c860b1ed

Platform Id

53152e93-cef7-e267-13ca-474a7717e614

Article author

@wadepickett

Metadata

• ID: 25051544-0e4d-1715-95b7-3a8616475127
• PlatformId: 53152e93-cef7-e267-13ca-474a7717e614
• Service: aspnet-core
• Sub-service: security

Related Issues

---

Associated WorkItem - 547103

[wadepickett]

@abatishchev, thanks very much for pointing this issue out and the details for fixing. Greatly appreciated!

[wadepickett]

🤖 AI Triage Summary

📌 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 and requires human review.

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-01-23
Issue: 36666
Model: GitHub Copilot

---

Issue Analysis: Code samples use AddAuthorization instead of recommended AddAuthorizationBuilder

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The code samples in the Claims-based authorization documentation use builder.Services.AddAuthorization(options => ...) pattern which triggers analyzer warning ASP0025. The recommended approach since .NET 7+ is to use AddAuthorizationBuilder() which is more concise and follows current best practices.

📁 Potentially Affected Files

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

File	Path	Lines	Section
Code sample	aspnetcore/security/authorization/claims/samples/6.x/WebAll/Program.cs	10-13	snippet region - EmployeeOnly policy
Code sample	aspnetcore/security/authorization/claims/samples/6.x/WebAll/Program.cs	41-45	snippet2 region - Founders policy

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

Potential Code Sample Updates

[Added corrected instruction here from Wade Pickett ]

A new 7.x code sample in its own 7.x folder needs to be created rather than changing the original 6.x sample which must be maintained. - Wade Pickett

File: aspnetcore/security/authorization/claims/samples/6.x/WebAll/Program.cs
Location: Lines 10-13 (snippet region)
Type: Replacement

Current code (lines 10-13):

builder.Services.AddAuthorization(options =>
{
   options.AddPolicy("EmployeeOnly", policy => policy.RequireClaim("EmployeeNumber"));
});

Suggested direction:

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("EmployeeOnly", policy => policy.RequireClaim("EmployeeNumber"));

---

A new 7.x code sample in its own 7.x folder needs to be created rather than changing the original 6.x sample which must be maintained. - Wade Pickett

File: aspnetcore/security/authorization/claims/samples/6.x/WebAll/Program.cs
Location: Lines 41-45 (snippet2 region)
Type: Replacement

Current code (lines 41-45):

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("Founders", policy =>
                      policy.RequireClaim("EmployeeNumber", "1", "2", "3", "4", "5"));
});

Suggested direction:

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("Founders", policy =>
        policy.RequireClaim("EmployeeNumber", "1", "2", "3", "4", "5"));

🎯 Suggested Action Plan

For documentation team review

A new 7.x code sample in its own 7.x folder needs to be created rather than changing the original 6.x sample which must be maintained. - Wade Pickett

1. Update code sample in a new 7.x folder: aspnetcore/security/authorization/claims/samples/6.x/WebAll/Program.cs

   • Navigate to: Lines 10-13 and Lines 41-45
   • Replace AddAuthorization(options => ...) pattern with AddAuthorizationBuilder()

2. Review related articles: Check if similar patterns exist in other authorization-related documentation that may also need updates

⚠️ Review Considerations

• The AddAuthorizationBuilder() method was introduced in .NET 7, so the aspnetcore-6.0+ moniker range is appropriate
• The markdown file references these code snippets via [!code-csharp[](~/security/authorization/claims/samples/6.x/WebAll/Program.cs?name=snippet...)] - the snippet names should remain unchanged
• Consider checking other authorization samples in the repository for consistency

🔗 References

• Published article: https://learn.microsoft.com/en-us/aspnet/core/security/authorization/claims?view=aspnetcore-10.0
• ASP0025 diagnostic: https://learn.microsoft.com/en-us/aspnet/core/diagnostics/asp0025?view=aspnetcore-10.0
• Source file: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/security/authorization/claims.md

[wadepickett]

Assigned to copilot after correcting the triage action paln we ran with copilot yesterday to verify how it migh handle it.