Lyo.Authentication 3.0.0

Lyo.Authentication

Server-side authentication services for Lyo. Two coexisting bearer formats behind a single contract:

• Format B opaque API tokens. lyo_<kind>_<ring>_<id>_<secret>, e.g. lyo_pat_live_01hxy8k2qf9_4f3b.... Store-backed, validated by DB lookup + constant-time SHA-256 comparison. For CLIs, services, integrations, webhooks, and refresh tokens. - Lyo-signed JWTs. Authorization: Bearer ey... (EdDSA / Ed25519). Short-lived, locally validated via JWKS. Issued by the Lyo API after a successful external OIDC login. For browser/mobile frontends and direct API callers.

This package has zero ASP.NET, EF, or HTTP dependencies, but it does depend on Lyo.KeyStore, Lyo.Hashing, and BouncyCastle for key/hash operations. Reserve it for the API/auth-server host. Do not reference it from consumer-side libraries or Blazor WebAssembly clients. Use Lyo.Authentication.Models instead for wire-shape DTOs, format helpers, and JWT parsing.

It owns:

• ApiTokenCodec. Mint + hash for Format-B tokens. Parse-only helpers live in Lyo.Authentication.Models. - IApiTokenIssuer / IApiTokenValidator. Opaque token lifecycle. - ILyoJwtIssuer / ILyoJwtValidator. Ed25519 JWT lifecycle, backed by Lyo.KeyStore for the signing key. - IUserStore / IExternalIdentityStore. Lyo user + linked-identity persistence. - IScopeRegistry. Fine-grained scope contract ({resource}.{action}). - IApiTokenStore. Token persistence. In-memory fallback included. - Ed25519KeyBootstrapper. IHostedService that auto-provisions a signing key on first run. - IAuthAuditRecorder / IAuthAuditContextAccessor / AuthAuditExtensions. Server-side audit recorder plumbing. The event records + enum taxonomy live in Lyo.Authentication.Models.

Examples

Register services

services.AddLyoAuthentication(configuration.GetSection(AuthenticationOptions.SectionName));
services.AddLyoJwtIssuer(); // uses IKeyStore for the signing key
services.AddInMemoryAuthenticationStores(); // swap for .Postgres in production
services.AddScope("people.read", "Read people");
services.AddScope("people.write", "Modify people records", implies: "people.read");

Configuration cheatsheet

{
  "LyoAuthentication": { "Ring": "live" },
  "LyoJwt": { "Issuer": "https://auth.lyo", "Audience": "lyo-api", "SigningKeyId": "lyo-sig" },
  "LyoSso": {
    "AllowedReturnOrigins": [ "https://app.example.com" ],
    "DefaultReturnUrl": "/",
    "HandoffCodeTtl": "00:00:30"
  },
  "PostgresUser": { "ConnectionString": "...", "EnableAutoMigrations": true }
}

Package layering

The auth stack is split so consumer-side libraries (including Blazor WebAssembly clients) cannot see server-only types:

ASP.NET wiring lives in Lyo.Authentication.AspNetCore. Postgres persistence and the Postgres audit recorder live in Lyo.Authentication.Postgres. The shared login host is Lyo.Authentication.Sso (MapLyoAuthEndpoints). OpenID Connect lives in Lyo.Authentication.OpenIdConnect with profiles Lyo.Authentication.Google and Lyo.Authentication.Keycloak. SAML lives in Lyo.Authentication.Saml with profiles Lyo.Authentication.Okta and Lyo.Authentication.Entra. The consumer-side BFF runtime lives in Lyo.Authentication.Client.

Typical host wiring (API/auth server)

A web host that issues both opaque tokens and JWTs, persists users + tokens + audit events to Postgres, and runs OIDC login through Google and Keycloak:

services.AddLyoAuthentication(builder.Configuration);
services.AddPostgresAuthenticationStoresFromConfiguration(builder.Configuration);
services.AddLyoApiTokenAuthentication(); // ASP.NET schemes + LyoBearer policy scheme
services.AddAuthorization();
services.AddLyoOpenIdConnect(builder.Configuration);
services.AddGoogleProviderFromConfiguration(builder.Configuration);
services.AddKeycloakProviderFromConfiguration(builder.Configuration);

app.UseAuthentication();
app.UseAuthorization();
app.MapLyoJwks(); // /.well-known/jwks.json
app.MapLyoAuthEndpoints(); // Lyo.Authentication.Sso: /auth/login/{provider}, /auth/callback/{provider}, /auth/handoff/exchange, /auth/token, /auth/refresh, /auth/logout, /auth/me
app.MapLyoTokenManagementEndpoints(); // /tokens (PAT lifecycle)

BFF flow for browser consumers (handoff)

• Browser hits GET /auth/sign-in/{provider}?returnUrl=/dashboard on the consumer (powered by Lyo.Authentication.Client). The consumer 302-redirects to GET https://api/auth/login/{provider}?returnUrl=https://consumer/auth/handoff&mode=browser.
• API seals PKCE+state+nonce in the HttpOnly lyo_oidc_state cookie and 302s to the IdP authorize endpoint.
• IdP redirects back to GET https://api/auth/callback/{provider}?code=...&state=.... The API unseals the cookie, exchanges the code for an id_token, validates signature/issuer/audience/nonce, runs the provider's claim mapper, looks up or JIT-provisions the LyoUser, links the external identity, mints a Lyo JWT + a rotating refresh token, stores them under a one-time handoff code (lyoh_…, TTL 30s), and 302-redirects to https://consumer/auth/handoff?lyo_handoff=lyoh_....
• Consumer's handoff endpoint POSTs { code: "lyoh_..." } to https://api/auth/handoff/exchange server-to-server with Origin: https://consumer. API verifies the origin matches the one the code was issued to, marks the code consumed, and returns { access_token, refresh_token, expires_in, token_type }.
• Consumer stashes the tokens in its server-side LyoAuthSessionStore and sets an HttpOnly lyo_session cookie containing only the data-protected session id. The browser sees nothing else.
• Outbound calls from the consumer to the API go through LyoAuthDelegatingHandler, which attaches Authorization: Bearer <access_token> and calls /auth/refresh (server-to-server) on 401 or near-expiry.
• GET /auth/sign-out on the consumer POSTs the refresh token to /auth/logout, then clears the local session cookie.

API-client flow (no browser)

• Hit GET https://api/auth/login/{provider}?mode=api&returnUrl=... from a controllable browser or system-browser webview. The callback returns JSON { access_token, refresh_token, expires_in, token_type } instead of a handoff redirect.
• Use Authorization: Bearer <access_token> against the API.
• When the access token nears expiry, POST /auth/refresh with body { "refresh_token": "lyo_rfr_live_..." }. The response is a rotated pair.
• POST /auth/logout with body { "refresh_token": "..." } to invalidate the family.

Per-provider knobs

• Google. See Lyo.Authentication.Google/README.md. Includes a Google Cloud + Lyo.TestApi + Lyo.TestGateway local walkthrough.
• Keycloak. See Lyo.Authentication.Keycloak/README.md. Includes a Docker-based local Keycloak walkthrough and the peer-vs-broker discussion.
• Custom. Implement IOpenIdConnectProvider and register it as a singleton. DefaultExternalLoginCoordinator will pick it up by name.

Auditing

Every meaningful auth state change emits an AuthAuditEvent through IAuthAuditRecorder. The default NullAuthAuditRecorder discards events. Lyo.Authentication.Postgres ships PostgresAuthAuditRecorder, which persists into the [user].[event] table. The kind column stores the enum's string name, e.g. JwtIssued. Ambient context (IP, User-Agent, correlation id) is pulled from the registered IAuthAuditContextAccessor. Defaults to NullAuthAuditContextAccessor. Lyo.Authentication.AspNetCore.AddLyoApiTokenAuthentication() swaps in HttpAuthAuditContextAccessor so rows carry the inbound caller's IP / User-Agent / trace id.

Closed taxonomy lives in AuthAuditEventKind:

Only append new members at the end of the enum. Its integer values are part of the on-disk schema.

Configuration cheatsheet

This package and its host-side siblings (Lyo.Authentication.OpenIdConnect, Lyo.Authentication.Postgres) own these sections. Provider-specific sections (GoogleAuth, KeycloakAuth, and others) and local-development walkthroughs (Google Cloud OAuth client, Keycloak Docker setup, environment promotion) live alongside the provider implementations themselves. See Lyo.Authentication.Google/README.md and Lyo.Authentication.Keycloak/README.md.

Dependencies

Generated from ProjectReference / PackageReference (same model as docs/Lyo.ProjectGraph.html).

• Lyo.Authentication.Models (direct, lyo)
• Lyo.Common.Core (direct, lyo)
• Lyo.Exceptions (direct, lyo)
• Lyo.Hashing (direct, lyo)
• Lyo.KeyStore (direct, lyo)
• BouncyCastle.Cryptography 2.6.2 (direct, third-party)
• Microsoft.Bcl.AsyncInterfaces 10.0.5 (direct, microsoft, netstandard2.0)
• Microsoft.Extensions.Configuration.Binder 10.0.5 (direct, microsoft)
• Microsoft.Extensions.Hosting.Abstractions 10.0.5 (direct, microsoft)
• Microsoft.Extensions.Options 10.0.5 (direct, microsoft)
• System.Text.Json 10.0.5 (direct, microsoft, netstandard2.0)
• Lyo.Common.Metadata (transitive, lyo)
• Konscious.Security.Cryptography.Argon2 1.3.1 (transitive, third-party)
• Microsoft.Extensions.DependencyInjection.Abstractions 10.0.5 (transitive, microsoft, net10.0, netstandard2.0)
• System.IO.Hashing 10.0.5 (transitive, microsoft, net10.0)
• System.Memory 4.6.3 (transitive, microsoft, netstandard2.0)