ClaimsPolicyBuilder 1.0.0

ClaimsPolicyBuilder

A fluent DSL for building ASP.NET Core claims-based authorization policies with compile-time safety.

Problem

Authorization in ASP.NET Core is powerful but ergonomically poor. AuthorizationPolicyBuilder requires 5–10 lines of repetitive policy.Require* calls per policy, uses magic strings for policy names, and offers no composition story.

Solution

ClaimsPolicyBuilder provides:

• A fluent DSL that expresses policies in 1–2 readable lines
• Compile-time policy name constants via a Roslyn source generator — typos become build errors, not runtime 403s
• Policy composition with Extends, And, and Or
• Zero runtime cost — produces standard AuthorizationPolicy instances

Installation

dotnet add package ClaimsPolicyBuilder

Quick Start

services.AddClaimsPolicies(policies =>
{
    policies.Add("CanEditInvoices")
        .RequireAuthenticated()
        .RequireScope("invoices:write")
        .RequireAnyRole("Accountant", "Admin")
        .RequireClaim("tenant", "acme");

    policies.Add("CanViewReports")
        .Extends("CanEditInvoices")
        .RequireClaim("feature", "reports");

    policies.Add("AdminOnly")
        .RequireRole("Admin")
        .Or(p => p.RequireClaim("override", "true"));
});

Using Generated Policy Name Constants

The source generator emits a Policies class with const string fields:

// Auto-generated at compile time
[Authorize(Policy = Policies.CanEditInvoices)]
public IResult EditInvoice() { ... }

[Authorize(Policy = Policies.AdminOnly)]
public IResult AdminAction() { ... }

Configure the Generated Namespace

Use an assembly attribute:

[assembly: ClaimsPolicyNamespace("MyApp.Auth")]

Or an MSBuild property in your .csproj:

<PropertyGroup>
  <ClaimsPolicyBuilder_Namespace>MyApp.Auth</ClaimsPolicyBuilder_Namespace>
</PropertyGroup>

Defaults to <RootNamespace>.Authorization.

API Reference

Policy Registration

Policy Builder

Source Generator Diagnostics

Examples

1. Simple Role-Based Policy

services.AddClaimsPolicies(policies =>
{
    policies.Add("AdminOnly").RequireRole("Admin");
});

2. Multi-Tenant Policy

services.AddClaimsPolicies(policies =>
{
    policies.Add("TenantAccess")
        .RequireAuthenticated()
        .RequireClaim("tenant", "acme");
});

3. Composed Policies

services.AddClaimsPolicies(policies =>
{
    policies.Add("BaseTenant")
        .RequireAuthenticated()
        .RequireClaim("tenant", "acme");

    policies.Add("TenantAdmin")
        .Extends("BaseTenant")
        .RequireRole("Admin");
});

4. OR Composition

services.AddClaimsPolicies(policies =>
{
    policies.Add("CanAccess")
        .RequireRole("Admin")
        .Or(p => p.RequireClaim("bypass", "true"));
});

5. Scope-Based API Policy

services.AddClaimsPolicies(policies =>
{
    policies.Add("ReadWrite")
        .RequireAuthenticated()
        .RequireScope("api:read", "api:write");
});

Sample App

A runnable ASP.NET Core sample lives in samples/ClaimsPolicyBuilder.Sample. It wires up every policy above and protects minimal-API endpoints with the generated Policies.* constants. A header-driven test auth handler lets you flip a request between allowed and denied without an identity provider:

dotnet run --project samples/ClaimsPolicyBuilder.Sample
# 200 — all requirements met
curl -i http://localhost:5080/invoices/edit \
  -H "X-User: alice" -H "X-Roles: Accountant" \
  -H "X-Scope: invoices:write" -H "X-Claims: tenant=acme"
# 403 — drop the scope and the same request is forbidden
curl -i http://localhost:5080/invoices/edit \
  -H "X-User: alice" -H "X-Roles: Accountant" -H "X-Claims: tenant=acme"

See the sample README and sample.http for the full success/denied matrix of every policy.

Design Decisions

• Extends semantics: Extending means logical AND of all requirements from the parent policy. Override semantics were considered but rejected as surprising in auth contexts.
• Or implementation: ASP.NET Core's policy model is AND-only by default. Or is implemented as a single RequireAssertion wrapping both sub-policies. This loses requirement-level introspection but provides correct OR evaluation.
• No replacement: The library produces standard AuthorizationPolicy instances. It integrates with existing [Authorize], minimal API .RequireAuthorization(), and Blazor <AuthorizeView>.

License

MIT