HexaSync Auth Middleware

Authentication middleware for HexaSync services. Validates JWTs signed with ECDSA (ES256/384/512) via JWKS, and HMAC (HS256/384/512) via a shared secret, choosing the path from the token's alg header.

Scope of this document: everything below describes the package as it is implemented today. If a knob is not listed here, it does not exist.

Installation

The package is published to the private feed https://nuget.hexasync.com/, not nuget.org — add it as a source first.

dotnet add package hexasync.auth.middleware --version 2609.7.1

Or in your .csproj — versions are calendar-based (YYMM.D.N, day not zero-padded: 2609.7.1 is 2026-09-07), so pin the current one rather than a semver-looking value:

<PackageReference Include="hexasync.auth.middleware" Version="2609.7.1" />

Quick Start

Environment variables (recommended)

SSO_SERVICE_URL=https://sso.hexasync.com    # SSO_URL is accepted as a legacy fallback
SSO_SERVICE_SECRET=your-hmac-secret         # only needed if this service receives HS* tokens
JWT_ISSUER=...                              # optional; see default in the table below
JWT_AUDIENCE=...                            # optional; see default in the table below

// Program.cs
builder.Services.AddHexaSyncAuthentication();

These are the only options this package reads from the environment — four options, across five variable names (SSO_URL is a legacy alias for SSO_SERVICE_URL). The package never binds IConfiguration itself, so the [ConfigurationKeyName] attributes on the options class are inert unless you bind configuration yourself — and bind the root, not the HexaSyncAuth section, because those attributes name flat keys (SSO_SERVICE_URL, not HexaSyncAuth__SsoUrl).

Configuring in code

builder.Services.AddHexaSyncAuthentication(options =>
{
    options.SsoUrl = "https://sso.hexasync.com";
    options.HmacSecretKey = builder.Configuration["Auth:HmacSecret"];
});

Configuration Options

Multiple Authentication Schemes

builder.Services.AddAuthentication()
    .AddHexaSync("HexaSync", options =>
    {
        options.SsoUrl = "https://sso.hexasync.com";
        options.HmacSecretKey = builder.Configuration["Auth:HmacSecret"];
    })
    .AddJwtBearer("AnotherScheme", options =>
    {
        // Other JWT configuration — AddJwtBearer needs
        // Microsoft.AspNetCore.Authentication.JwtBearer, which this package does not reference
    });

What AddHexaSync* Registers

• IJwksKeyProvider → JwksKeyProvider (via AddHttpClient, so the concrete registration is transient)
• IDualModeTokenValidator → DualModeTokenValidator (singleton)
• IEcdsaInnerServiceTokenResolver → StandardEcdsaInnerServiceTokenResolver (scoped, TryAdd)
• IMemoryCache
• The HexaSync authentication scheme and its handler

Token Validation

Validation routes on the JWT header alg:

The handler adds a token_validation_method claim recording which path succeeded:

var method = User.FindFirst("token_validation_method")?.Value;   // "ECDSA" or "HMAC"

Capability-Based Authorization

Capabilities are resolved automatically during authentication by HexaSyncAuthenticationHandler — there is no middleware to add and no separate registration call in this package.

Prerequisite

Resolution needs a working IEcdsaInnerServiceTokenResolver. AddHexaSync* registers the type with TryAddScoped, but its dependencies — an HttpClient, IOptions<ClientCredentialsOptions>, IDistributedCache and an EcdsaTokenRefreshCoordinator — come from the hexasync.services.proxy package:

builder.Services.AddEcdsaInnerServiceResolver(builder.Configuration);
// env: SSO_SERVICE_URL, SSO_CLIENT_ID, SSO_CLIENT_SECRET

If the resolver cannot be obtained, capability resolution is skipped and the request proceeds with no capabilities.

Resolution flow

Driven by the system_role claim, then narrowed by the calling application:

There is no first-party branch in the code. One rule decides all three rows: an application that declares capabilities narrows the caller to the intersection; one that declares nothing does not narrow (so the caller keeps its full user set); one whose capabilities cannot be resolved gets nothing (fail-closed); and a token carrying no client_id is granted nothing. See CapabilityIntersection and ApplicationCapabilityStatus for the exact rule.

Protecting endpoints

// Minimal API — OR (any of)
app.MapGet("/users", GetUsers).RequireCapability("users:read", "admin:full_access");

// Minimal API — AND (all of)
app.MapPost("/users", CreateUser).RequireAllCapabilities("users:write", "audit:enabled");

// Minimal API — require active sudo mode (re-verified identity).
// Otherwise 403 with body {"code":"SUDO_REQUIRED","message":"…"} — note the property is `code`, not `error`.
app.MapDelete("/users/{id}", DeleteUser).RequireSudo();

// MVC
[RequireCapability("users:read", "admin:full_access")]
public IActionResult GetUsers() { ... }

[RequireCapability("users:write", "audit:enabled", RequireAll = true)]
public IActionResult CreateUser() { ... }

Checking capabilities in code

using hexasync.auth.middleware.Capabilities;

if (httpContext.HasCapability(AppCapabilities.Sso.OAuthApps.Write)) { ... }

if (httpContext.HasAnyCapability(AppCapabilities.Sso.OAuthApps.Read, "admin:full_access")) { ... }

if (httpContext.HasAllCapabilities(AppCapabilities.Sso.OAuthApps.Read,
                                   AppCapabilities.Sso.OAuthApps.Write)) { ... }

IReadOnlyList<string> capabilities = httpContext.GetCapabilities();

AppCapabilities holds the constants — e.g. AppCapabilities.Sso.OAuthApps.Read is "identity:oauth_apps:read".

Other extensions

using hexasync.auth.middleware.Extensions;

Guid? userId   = httpContext.GetUserId();          // null for SERVICE tokens, or when no user id claim is present
Guid  required = httpContext.GetRequiredUserId();  // throws in those same cases
string? client = httpContext.GetClientId();

bool isService = httpContext.IsServiceToken();     // how you tell a client-credentials token from a user one
bool isUser    = httpContext.IsUserToken();

Guid? roleId = User.GetSystemRoleId();             // extension on ClaimsPrincipal, not HttpContext

RequireSudo() performs a claims-based check. If you register an ISudoValidationService, it is also consulted — but only when the claims check has already passed and the token carries both sudo_iat and sub in parseable form. A sudo token missing either skips the service entirely and is accepted on the claims check alone, so this is a server-side invalidation hook rather than an unconditional gate.

Security Considerations

1. Use HTTPS for SsoUrl. RequireHttpsMetadata exists as an option but nothing enforces it, so this is on you.
2. Store SSO_SERVICE_SECRET in a secret manager. It is a symmetric key shared across services: anyone holding it can mint a token every service accepts.
3. Key rotation. JWKS keys are cached for JwksCacheDuration (24 hours by default, plus the 6-hour sliding expiry noted in the options table). A token bearing an unknown kid triggers one refresh and one retry, so a newly published key is picked up without waiting for the cache to expire.
4. Clock skew. 5 minutes by default.

Troubleshooting

JWKS fetch fails — check connectivity to {SsoUrl}/.well-known/jwks.json, certificate validity, and firewall rules. On failure the provider returns an empty key set and validation fails closed.

Token validation fails — check expiry, issuer/audience against the defaults in the options table (they are constants, not derived from SsoUrl), and clock sync between services.

Options are unexpectedly at their defaults — you are probably on an Action<HexaSyncAuthOptions> overload, which does not read environment variables. See the note under Quick Start.

Capabilities are always empty — AddEcdsaInnerServiceResolver is probably not registered, or the token carries no system_role / client_id claim. A missing resolver and a missing system_role log at Debug; a token with no client_id, and a resolver that throws, log at Warning.

Unexplained 403s — subscribe to the meter hexasync.auth.capability (CapabilityTelemetry.MeterName); it exposes a hexasync.auth.capability.denied counter (CapabilityTelemetry.DeniedCounterName) incremented once per denial and tagged with reason (see CapabilityDenialReasons). Note the counter name is not the meter name — subscribing to hexasync.auth.capability.denied matches no meter and emits nothing, silently.

For a single request, CapabilityResolution.From(httpContext) returns the resolved set plus the ApplicationCapabilityStatus — or null when authentication did not run or resolution bailed out early, i.e. no system_role claim or no resolver registered. Those are the two Debug cases above, so a null here is itself the answer.

License

MIT