IronAlpine.Security 2.1.1

IronAlpine.Security

IronAlpine.Security is the unified security package for:

• current user access (ICurrentUser, IAuditUser),
• JWT authentication setup,
• dynamic permission policy resolution,
• policy catalog registration from Smart Enum-like types,
• EF Core-backed permission projection store,
• SignalR access token-from-query support.

Installation

<PackageReference Include="IronAlpine.Security" Version="2.0.9" />

What This Package Provides

• ASP.NET Core integration:
  • AddIronAlpineSecurityJwt(...)
  • AddIronAlpineSecurityAspNetCore(...)
  • WithSignalR(...)
  • AddPolicyCatalog<TPermission>(...)
• Permission engine:
  • IPermissionCheckerService
  • ISecurityPermissionStore
  • ISecurityPermissionProjectionSyncStore
• EF Core store:
  • AddIronAlpineAuthorizationEfCore<TDbContext>(...)
  • WithAuthorizationStoreEfCore<TDbContext>(...)
• Authorization helpers:
  • AuthorizeAnyPermissionAttribute

Configuration

IronAlpine:Security:AspNetCore

{
  "IronAlpine": {
    "Security": {
      "AspNetCore": {
        "Permission": {
          "PermissionGroupClaimType": "groups",
          "StartupValidationEnabled": true
        },
        "Jwt": {
          "Issuer": "your-issuer",
          "Audience": "your-audience",
          "Secret": "your-very-strong-secret",
          "ValidateIssuer": true,
          "ValidateAudience": true,
          "ValidateLifetime": true,
          "ValidateIssuerSigningKey": true,
          "ClockSkewSeconds": 0
        },
        "SignalR": {
          "EnableAccessTokenFromQuery": false,
          "HubPaths": []
        },
        "AuditClaims": {
          "UserIdKeys": [ "sub", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", "oid" ],
          "UserNameKey": "name",
          "EmailKey": "email",
          "RoleKey": "role"
        }
      }
    }
  }
}

IronAlpine:Security:Authorization

{
  "IronAlpine": {
    "Security": {
      "Authorization": {
        "PermissionGroupClaimType": "groups"
      }
    }
  }
}

IronAlpine:Security:Authorization:EFCore

{
  "IronAlpine": {
    "Security": {
      "Authorization": {
        "EFCore": {
          "PermissionProjectionTableName": "SecurityPermissionProjections",
          "PermissionProjectionSchema": null,
          "PermissionNameMaxLength": 256
        }
      }
    }
  }
}

Scenario 1: Standard JWT + Permission Policies

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

Use standard policy attributes:

[Authorize(Policy = nameof(Permissions.EducationCreate))]
public sealed class EducationController : ControllerBase
{
}

Or OR semantics with multiple policies:

[AuthorizeAnyPermission(nameof(Permissions.EducationCreate), nameof(Permissions.EducationUpdate))]
public sealed class EducationController : ControllerBase
{
}

Scenario 2: Add EF Core Permission Store

When permission data is stored in your service database:

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

Alternative registration style:

builder.Services.AddIronAlpineAuthorizationEfCore<AppDbContext>();

EF Core modeling notes

The package contributes SecurityPermissionProjection model automatically through model contributors. It creates a table (default: SecurityPermissionProjections) with:

• PermissionGroupId (Guid),
• PermissionId (int),
• PermissionName (string).

Scenario 3: Smart Enum Policy Catalog

AddPolicyCatalog<TPermission>() expects TPermission to expose:

• static GetValues(),
• static GetFieldName(TPermission value),
• instance Name.

If these members are missing, startup fails with a clear InvalidOperationException.

Prefix support:

builder.Services
    .AddIronAlpineSecurityJwt(builder.Configuration)
    .AddPolicyCatalog<Permissions>(prefix: "api:");

Scenario 4: Custom Permission Mapping

If policy name to permission name mapping must be customized:

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

Or provide a custom catalog:

var entries = new[]
{
    new PermissionCatalogEntry("EducationCreatePolicy", "education:create"),
    new PermissionCatalogEntry("EducationUpdatePolicy", "education:update")
};

builder.Services
    .AddIronAlpineSecurityJwt(builder.Configuration)
    .WithPermissionCatalog(new InMemoryPermissionCatalog(entries));

Scenario 5: SignalR Token From Query String

Enable query-string token for hub endpoints:

builder.Services
    .AddIronAlpineSecurityJwt(builder.Configuration)
    .WithSignalR("/hubs/notifications", "/hubs/chat")
    .AddPolicyCatalog<Permissions>();

This sets JwtBearerEvents.OnMessageReceived and reads access_token only for configured hub paths.

Scenario 6: Current User Without JWT Setup

If you only need ICurrentUser and audit abstractions in a specific service:

builder.Services.AddIronAlpineSecurityAspNetCore();

Permission Resolution Flow

1. Authorize policy is requested.
2. PermissionPolicyProvider resolves policy name to permission name.
3. PermissionAuthorizationHandler queries permissions from IPermissionCheckerService.
4. PermissionCheckerService reads group claims (PermissionGroupClaimType, default groups).
5. ISecurityPermissionStore returns owned permission names.
6. Requirement succeeds when any required permission is owned.

Troubleshooting

All endpoints return 403

Check these first:

• JWT token contains the configured group claim type (default groups).
• Group claim values are valid GUIDs.
• Policy names used in [Authorize(Policy=...)] exist in catalog.
• Permission projection table contains matching permission names for claimed group ids.
• PermissionGroupClaimType is consistent across:
  • IronAlpine:Security:AspNetCore:Permission:PermissionGroupClaimType
  • IronAlpine:Security:Authorization:PermissionGroupClaimType

Startup validation failure for policies

If StartupValidationEnabled is true, known policies must be resolvable by the active policy resolver. Set to false only if you intentionally manage policy resolution at runtime.

Migration From Previous Split Packages

Replace these package references:

• IronAlpine.Security.Abstractions
• IronAlpine.Security.AspNetCore
• IronAlpine.Security.Authorization
• IronAlpine.Security.Authorization.EFCore

with a single reference:

<PackageReference Include="IronAlpine.Security" Version="2.0.9" />