IronAlpine.Security.AspNetCore 2.0.0

IronAlpine.Security.AspNetCore

IronAlpine.Security.AspNetCore is the ASP.NET Core security runtime for IronAlpine services.

It standardizes:

• JWT bearer validation
• current-user resolution
• permission-based authorization
• policy-catalog generation
• SignalR token extraction from query strings

Why

Use this package when a service is an HTTP entry point that validates access tokens and enforces permission policies.

This package exists so services stop maintaining custom JWT setup, duplicated authorization handlers, and hand-written policy registration loops.

Install

dotnet add package IronAlpine.Security.AspNetCore

Quick Start

builder.Services
    .AddIronAlpineSecurityJwt(builder.Configuration)
    .WithAuthorizationCore()
    .AddPolicyCatalog<Permissions>()
    .WithSignalR("/hubs/messenger");

Configuration

Configuration root:

{
  "IronAlpine": {
    "Security": {
      "AspNetCore": {
        "Jwt": {
          "Issuer": "https://identity.example.com",
          "Audience": "personnel-api",
          "Secret": "very-strong-signing-secret"
        },
        "Permission": {
          "PermissionGroupClaimType": "groups",
          "StartupValidationEnabled": true
        },
        "SignalR": {
          "EnableAccessTokenFromQuery": true,
          "HubPaths": [
            "/hubs/messenger"
          ]
        }
      }
    }
  }
}

Public Surface

Main entry point:

• AddIronAlpineSecurityJwt(...)

Fluent extensions:

• WithAuthorizationCore()
• AddPolicyCatalog<TPermission>()
• WithPermissionCatalog(...)
• WithSmartEnumCatalog(...)
• WithSignalR(...)

Options Deep Dive

JWT options

Bound from IronAlpine:Security:AspNetCore:Jwt.

Issuer

• no safe default
• expected token issuer
• mismatch causes token validation failure

Audience

• no safe default
• expected audience for this service
• best practice: make this service-specific

Secret

• no safe default
• symmetric signing key for HMAC validation scenarios
• store it securely; do not hardcode in code or commit it to source control

Permission options

PermissionGroupClaimType

• default: groups
• claim type used for incoming permission-group values
• change only if your identity provider uses a different claim name

StartupValidationEnabled

• default: true
• validates policy wiring and resolver/catalog consistency on startup
• keep this enabled in production unless you have a measured reason not to

SignalR options

EnableAccessTokenFromQuery

• default: false
• when enabled, JWT can be extracted from SignalR query-string tokens for configured hubs
• do not enable globally unless SignalR is actually used

HubPaths

• default: empty
• list of hub paths allowed to read access tokens from query string
• keep this explicit; do not use broad path matching

AddIronAlpineSecurityJwt(...)

This registers:

• JWT bearer authentication
• current-user runtime services
• permission policy provider
• permission authorization handler
• configuration/options validation

Example with explicit overrides:

builder.Services.AddIronAlpineSecurityJwt(
    builder.Configuration,
    options =>
    {
        options.Jwt.Audience = "identity-admin-api";
        options.Permission.PermissionGroupClaimType = "roles";
    });

Policy Catalogs

Reflection-based catalog

builder.Services
    .AddIronAlpineSecurityJwt(builder.Configuration)
    .AddPolicyCatalog<Permissions>();

Use this when the permission type exposes:

• static GetValues()
• static GetFieldName(...)
• instance Name

Explicit smart-enum catalog

builder.Services
    .AddIronAlpineSecurityJwt(builder.Configuration)
    .WithSmartEnumCatalog(Permissions.GetValues(), Permissions.GetFieldName, x => x.Name);

Manual catalog

Use WithPermissionCatalog(...) when permissions come from another source and you want full control over policy names and permission names.

SignalR Token Support

WithSignalR(...) enables query-string token extraction only for the given hub paths.

This preserves normal JWT bearer behavior for the rest of the application while keeping browser SignalR clients compatible.

Pair this with IronAlpine.Web.AspNetCore CORS configuration so allowed origins and credential rules line up.

Current User Integration

The package provides an ASP.NET Core ICurrentUser / IAuditUser implementation backed by HttpContext.

This matters for:

• controller/user context access
• EF Core auditing
• inbox/outbox replay audit trail

Combinations

Security + Authorization.EFCore

Use IronAlpine.Security.Authorization.EFCore when permission projections must be synchronized into the database for query-side authorization or administrative views.

Security + Web.AspNetCore

Use with IronAlpine.Web.AspNetCore so request metadata and exception behavior are standardized alongside authentication.

Security + Messaging

When handlers produce integration events, the current-user identity and audit actor information stay aligned across HTTP and data layers.

Troubleshooting

All requests return 401

Cause:

• issuer, audience, or secret mismatch

Fix:

• verify Jwt options exactly match the issuing identity service

Policies do not resolve

Cause:

• policy catalog not registered
• custom resolver mismatches policy names

Fix:

• enable startup validation
• register AddPolicyCatalog<TPermission>() or explicit catalog wiring

SignalR connects but hub methods fail authorization

Cause:

• query-string token extraction disabled
• hub path not registered

Fix:

• call WithSignalR(...)
• verify hub path matches the actual mapped path

Startup fails during validation

Cause:

• permission catalog or resolver produced inconsistent policy names

Fix:

• inspect catalog registration
• keep StartupValidationEnabled on and fix the mismatch rather than suppressing it