Clywell.Core.Security 1.0.0

Clywell.Core.Security

Security primitives for .NET — JWT bearer configuration, user context resolution, permission-based authorization, and security headers middleware.

Installation

dotnet add package Clywell.Core.Security

Table of Contents

• Quick Start
• JWT Authentication
  • OIDC / External Identity Provider
  • Self-Hosted JWT (Symmetric Key)
  • Token from Cookie or Query String
• Current User
• Permission-Based Authorization
• Custom User Context Resolver
  • Type-Parameter Registration
  • Factory Registration
• Custom Claim Mapping
• Security Headers
• API Reference
• Dependencies

Quick Start

1. Register services

builder.Services.AddSecurity(options =>
{
    options.AddJwtBearer()
           .WithOidcProvider("https://your-identity-provider.com", audience: "your-api");
});

2. Configure the middleware pipeline

app.UseAuthentication();
app.UseUserContext();      // Populates ICurrentUser from the resolved identity
app.UseAuthorization();
app.UseSecurityHeaders();  // Adds OWASP-recommended response headers

3. Inject ICurrentUser

public class MyService(ICurrentUser currentUser)
{
    public void DoWork()
    {
        if (!currentUser.IsAuthenticated)
            return;

        Console.WriteLine(currentUser.UserId);
        Console.WriteLine(currentUser.Email);
        Console.WriteLine(currentUser.IpAddress);

        if (currentUser.IsInRole("Admin")) { /* ... */ }
        if (currentUser.HasPermission("articles.edit")) { /* ... */ }
    }
}

JWT Authentication

AddJwtBearer() returns a JwtBearerBuilder. Pick your token source first, then optionally chain transport and advanced settings.

OIDC / External Identity Provider

Use WithOidcProvider when tokens are issued by an external provider (Auth0, Azure AD, Keycloak, etc.). Signing keys are discovered automatically.

options.AddJwtBearer()
       .WithOidcProvider("https://login.example.com", audience: "my-api");

Advanced settings chain naturally:

options.AddJwtBearer()
       .WithOidcProvider("https://login.example.com", audience: "my-api")
       .WithClockSkew(TimeSpan.FromSeconds(30))
       .DisableAudienceValidation();  // only if your IdP omits aud

Self-Hosted JWT (Symmetric Key)

Use WithSymmetricKey when your own service issues JWTs with no external OIDC provider.

Security: The signing key must be at least 32 characters. Read it from a secret manager or environment variable — never hard-code it.

options.AddJwtBearer()
       .WithSymmetricKey(
           signingKey: builder.Configuration["Jwt:SigningKey"], // min 32 chars
           issuer:     "https://my-service.example.com",
           audience:   "my-api");

Token from Cookie or Query String

For transports that cannot send an Authorization header (SignalR WebSockets, SSE), chain WithTokenCookie and/or WithTokenQueryParam. Cookie takes priority over query string when both are present.

Security: The cookie should be HttpOnly and Secure. Query string tokens may appear in server logs — prefer cookies where possible.

options.AddJwtBearer()
       .WithOidcProvider("https://login.example.com", audience: "my-api")
       .WithTokenCookie("access_token")      // HttpOnly, Secure cookie
       .WithTokenQueryParam("access_token"); // fallback when cookie absent

Current User

ICurrentUser is a scoped service populated per-request by UseUserContext(). It exposes:

Custom properties on UserInfo

UserInfo accepts an optional ImmutableDictionary<string, object> for arbitrary per-request data (e.g. tenant metadata resolved from the token). Access it via GetProperty<T>():

var userInfo = new UserInfo(
    userId,
    email,
    displayName,
    roles,
    permissions,
    Properties: ImmutableDictionary<string, object>.Empty
        .Add("tenantId", "tenant-abc")
        .Add("plan", "pro"));

// Later, in any service:
var tenantId = currentUser.GetProperty<string>("tenantId");

Permission-Based Authorization

Decorate controllers or actions with [HasPermission]. Multiple attributes require all permissions (AND semantics).

[HasPermission("articles.edit")]
public IActionResult EditArticle(int id) { ... }

[HasPermission("articles.delete")]
[HasPermission("articles.edit")]   // user must have BOTH
public IActionResult DeleteArticle(int id) { ... }

Policies are resolved dynamically by PermissionPolicyProvider — no manual policy registration required.

Custom User Context Resolver

The default ClaimsUserContextResolver reads identity data straight from JWT claims. To load roles or permissions from a database (or any other source), implement IUserContextResolver.

Type-Parameter Registration

public class DatabaseUserContextResolver(
    IUserRepository userRepo) : IUserContextResolver
{
    public async Task<UserInfo?> ResolveAsync(HttpContext context)
    {
        if (context.User.Identity?.IsAuthenticated != true)
            return null;

        var userId = context.User.FindFirstValue("sub");
        if (userId is null) return null;

        var user = await userRepo.GetByIdAsync(userId);
        if (user is null) return null;

        return new UserInfo(
            userId,
            user.Email,
            user.DisplayName,
            user.Roles.ToHashSet(),
            user.Permissions.ToHashSet());
    }
}

// Registration
builder.Services.AddSecurity(options =>
    options.UseResolver<DatabaseUserContextResolver>());

Factory Registration

Use the factory overload when the resolver depends on services not available at configuration time:

builder.Services.AddSecurity(options =>
    options.UseResolver(sp =>
    {
        var repo = sp.GetRequiredService<IUserRepository>();
        return new DatabaseUserContextResolver(repo);
    }));

Custom Claim Mapping

ClaimsUserContextResolver reads claims using the names defined in UserClaimMapping. Override any of them via ConfigureClaimMapping() if your identity provider uses non-standard claim types:

builder.Services.AddSecurity(options =>
{
    options.AddJwtBearer(jwt => { /* ... */ });

    options.ConfigureClaimMapping(mapping =>
    {
        mapping.UserId      = "oid";              // Azure AD object ID
        mapping.Email       = "preferred_username";
        mapping.DisplayName = "name";             // default — shown for clarity
        mapping.Roles       = "roles";            // Azure AD app roles
        mapping.Permissions = "scp";              // OAuth 2 scopes as permissions
    });
});

Default claim type mapping:

Security Headers

UseSecurityHeaders() adds the following response headers and strips server-identifying headers:

API Reference

SecurityOptions

JwtBearerBuilder

ICurrentUser

Scoped service available after UseUserContext() runs in the pipeline. See the Current User section for the full member table.

UserInfo

public sealed record UserInfo(
    string UserId,
    string? Email = null,
    string? DisplayName = null,
    IReadOnlySet<string>? Roles = null,
    IReadOnlySet<string>? Permissions = null,
    ImmutableDictionary<string, object>? Properties = null);

Returned by IUserContextResolver.ResolveAsync() to describe the resolved identity for the current request.

SecurityClaimTypes

Constants for common JWT claim type names:

SecurityClaimTypes.Subject    // "sub"
SecurityClaimTypes.Email      // "email"
SecurityClaimTypes.Name       // "name"
SecurityClaimTypes.Role       // "role"
SecurityClaimTypes.Permission // "permission"

Dependencies

• Microsoft.AspNetCore.App (framework reference — no extra NuGet download)
• Microsoft.AspNetCore.Authentication.JwtBearer

License

MIT — see LICENSE.