Genocs.Auth

Genocs.Auth — Agent Reference Documentation

Consumer Mode for Agents #

• Assume package is installed from NuGet
• Do not rely on repository source code access
• Prefer stable public APIs and extension methods documented here
• If behavior is uncertain, fail safely and request config/package version details.

Purpose #

Genocs.Auth provides JWT authentication registration, token handling, and optional access-token revocation validation.

Quick Facts #

Install #

dotnet add package Genocs.Auth

Minimal Integration Recipe (Program.cs) #

using Genocs.Auth;
using Genocs.Core.Builders;

var builder = WebApplication.CreateBuilder(args);

IGenocsBuilder gnxBuilder = builder
    .AddGenocs()
    .AddJwt();

gnxBuilder.Build();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.UseAccessTokenValidator();
app.Run();

Configuration #

Use the jwt section.

{
  "jwt": {
    "enabled": true,
    "algorithm": "HS256",
    "issuer": "https://identity.example.com",
    "issuerSigningKey": "your-secret-key",
    "authority": "https://identity.example.com",
    "audience": "orders-api",
    "challenge": "Bearer",
    "metadataAddress": "/.well-known/openid-configuration",
    "saveToken": true,
    "saveSigninToken": false,
    "requireAudience": true,
    "requireHttpsMetadata": true,
    "requireExpirationTime": true,
    "requireSignedTokens": true,
    "expiryMinutes": 60,
    "validAudience": "orders-api",
    "validAudiences": ["orders-api", "admin-api"],
    "validIssuer": "https://identity.example.com",
    "validIssuers": ["https://identity.example.com"],
    "validateActor": false,
    "validateAudience": true,
    "validateIssuer": true,
    "validateLifetime": true,
    "validateTokenReplay": false,
    "validateIssuerSigningKey": true,
    "refreshOnIssuerKeyNotFound": true,
    "includeErrorDetails": true,
    "authenticationType": "Bearer",
    "nameClaimType": "name",
    "roleClaimType": "Role",
    "allowAnonymousEndpoints": ["/health", "/metrics"],
    "certificate": {
      "location": "certs/signing.pfx",
      "rawData": null,
      "password": "change-me"
    }
  }
}

Use issuerSigningKey for shared-secret or raw RSA-key scenarios. Use certificate.* when token signing or validation should rely on X.509 material.

Decision Matrix For Agents #

Behavior Notes / Constraints #

• jwt.enabled = false disables authentication checks and is suitable only for controlled non-production scenarios.
• Default token deactivation state is process-local unless a distributed implementation is provided.
• Token validation behavior depends directly on issuer, audience, signing, and lifetime settings.

Public Capability Map #

• Authentication registration: AddJwt(), AddOpenIdJwt(), AddPrivateKeyJwt()
• Token operations: IJwtHandler
• Token deactivation and checks: IAccessTokenService, UseAccessTokenValidator()
• ASP.NET Core pipeline integration: standard UseAuthentication() and UseAuthorization()

Dependencies #

• Genocs.Core
• Genocs.Security
• Microsoft.AspNetCore.Authentication.JwtBearer

Troubleshooting #

1. Protected endpoints always return unauthorized responses. Fix: Confirm jwt values (issuer, audience, signing key/certificate) and middleware order in the HTTP pipeline.
2. A revoked token still succeeds on another instance. Fix: Replace default in-memory token deactivation storage with a distributed implementation.
3. Application fails during JWT startup validation. Fix: Validate signing material format and ensure issuer/audience settings match token contents.