Lyo.Authentication.OpenIdConnect 1.0.6

Lyo.Authentication.OpenIdConnect

OpenID Connect client base for Lyo. The Lyo API is the OIDC confidential client (BFF pattern). The frontend never sees the IdP and never receives tokens by URL fragment. After a successful external login, the API either:

• issues tokens directly as JSON, for API clients calling /auth/login/{provider}?mode=api, or - mints a single-use handoff code and 302-redirects the browser to a whitelisted consumer origin, which then exchanges that code server-to-server for the tokens, for browser clients via Lyo.Authentication.Client.

Examples

Register services

services.AddLyoOpenIdConnect(builder.Configuration);
services.AddGoogleProviderFromConfiguration(builder.Configuration);
services.AddKeycloakProviderFromConfiguration(builder.Configuration);

Building blocks

• IOpenIdConnectProvider. Abstraction describing a provider: discovery URL, client id/secret, scope/claim mapping.
• OpenIdConnectProviderRegistry. Keyed by name, resolved at /auth/login/{name}.
• OidcDiscoveryCache. Hourly-refreshed OpenID Configuration cache.
• OidcJwksResolver. Fetches and caches the provider's JWKS for id_token signature verification.
• PkceCodes + StateNonceProtector. Generate and seal PKCE/state/nonce in an HTTP-only cookie via IDataProtector.
• OidcAuthorizationUrlBuilder. Composes the /authorize URL with code_challenge, state, nonce.
• OidcTokenExchangeClient. Typed HttpClient that POSTs the authorization code back for tokens.
• OidcIdTokenValidator. Validates issuer, audience, nonce, exp, signature.
• IExternalLoginCoordinator / DefaultExternalLoginCoordinator. Wraps the whole flow: discover-or-link-or-create the Lyo user, refresh linked_identity.scopes_json, and call ILyoJwtIssuer.IssueAsync. Emits AuthAuditEventKind.{ExternalLoginSucceeded,ExternalLoginRejected,UserProvisioned,IdentityLinked} along the way.
• IHandoffCodeStore / InMemoryHandoffCodeStore. Single-use, TTL-bounded handoff codes (browser handoff path).

Endpoints

app.MapLyoAuthEndpoints() wires:

Registration

That call binds two option sections. LyoExternalLogin sets Sealing.{Purpose,DefaultExpiration} and the cookie name for the PKCE/state envelope. LyoOidcBff is documented under BFF options below. The per-provider packages register their IOpenIdConnectProvider implementation under their canonical name (google, keycloak:<realm>).

BFF options

{
  "LyoOidcBff": {
    "AllowedReturnOrigins": [ "http://localhost:5138", "https://app.example.com" ],
    "DefaultReturnUrl": "/",
    "HandoffCodeTtl": "00:00:30"
  }
}

• AllowedReturnOrigins. Exact origin (scheme://host[:port]) match for absolute returnUrl values and Origin checks on /auth/handoff/exchange. Same-origin relative returnUrl starting with / is always allowed. Anything outside the allowlist falls back to DefaultReturnUrl.
• DefaultReturnUrl. Used when returnUrl is missing or rejected.
• HandoffCodeTtl. Short. 30s is plenty. The consumer redeems immediately on the redirect.

Auditing

Every meaningful state transition emits an AuthAuditEvent. With Lyo.Authentication.Postgres wired up these land in [user].[event]. The kind column stores the enum's string name, JwtIssued, HandoffCodeIssued, and so on. Otherwise they hit whatever IAuthAuditRecorder is registered, default NullAuthAuditRecorder. IP, User-Agent, and correlation come from the registered IAuthAuditContextAccessor. Call services.AddLyoApiTokenAuthentication() or services.AddLyoAuthHttpContextAccessor() standalone on an ASP.NET host to swap in HttpAuthAuditContextAccessor.

Talking to it

• Browser consumers. Use Lyo.Authentication.Client for handoff redemption, the session cookie, and LyoAuthDelegatingHandler for outbound refresh.
• API clients. Call /auth/login/{provider}?mode=api and consume the JSON token response directly. Call /auth/refresh when the access token nears expiry.

Dependencies

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

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