feat(auth): generic external SSO / OIDC login + refresh-token sessions + docs (#328)

* feat(auth): add generic external SSO / OIDC login provider (#327)

Delegate PoracleWeb login to any external OAuth2/OpenID Connect provider, alongside the built-in Discord and Telegram methods. Enables single sign-on (e.g. pointing PoracleWeb at the PogoAlerts OAuth2 server) while staying provider-agnostic so any self-hoster can configure their own IdP.

Implemented as a configurable twin of the Discord flow:
- OidcSettings (URLs, client id/secret, scopes, claim mapping, PKCE flag)
- GET /api/auth/oidc/login + /callback: auth-code exchange with PKCE, CSRF state in HttpOnly cookies; reads a configurable identity claim (default discord_id, falls back to sub), looks it up in the human table, reuses GetRolesAsync + guild-role gating, mints the existing internal JWT
- providers endpoint gains an oidc block; enable_oidc site-setting runtime toggle (admins can always log in to re-enable); OIDC_* env bridge with auto-infer; documented in .env.example
- Frontend: oidc provider model, loginWithOidc(), /auth/oidc/callback route, login button + disabled hint + error codes, admin External SSO group, English i18n keys

Tests: backend providers oidc block + /oidc/login redirect/PKCE (1394 pass); frontend OIDC button visibility + click delegation (48 pass).

* feat(auth): OIDC refresh-token sessions, SSO refinements, and docs

Optional, provider-agnostic consumption of the external SSO provider's refresh
token for silent session renewal + revocation propagation (default OFF via
OIDC_USE_REFRESH_TOKENS), plus surrounding SSO login refinements and a
comprehensive OIDC documentation set. Fully OIDC-provider-agnostic; PogoAlerts
is only the reference provider.

Backend:
- oidc_sessions table (EF migration AddOidcSessions): the provider refresh token
  is stored server-side, DataProtection-encrypted, never sent to the browser; the
  browser holds only an opaque rotating token keyed to a rotation family.
- POST /api/auth/oidc/refresh (rotate + live user re-validation + family-revoke on
  replay/provider-revoke) and /oidc/refresh/revoke; OidcSessionCleanupService reaps
  expired/stale rows (OIDC_SESSION_REVOKED_RETENTION_DAYS, default 2).
- Provider-agnostic IOidcClient shared by login callback and refresh: configurable
  client_secret_post|client_secret_basic, optional/non-rotating refresh tokens,
  offline_access auto-appended; no discovery/JWKS/id_token dependency.
- Per-login short JWT for refresh-backed OIDC sessions (OIDC_ACCESS_TOKEN_MINUTES,
  default 30); Discord/Telegram/local logins keep the 24h JWT.
- Refresh is env-controlled only (no runtime admin toggle — coupled to JWT lifetime).

Frontend:
- TokenStoreService (single-flight refresh) + oidcRefreshInterceptor (proactive
  pre-expiry + reactive 401-retry, null-refresh-token guard so non-refresh logins
  keep the existing 401->logout path); callback stores the opaque token; logout
  revokes the session server-side.
- SSO login refinements: Local/SSO auth-mode switch, single-logout toggle,
  auto-redirect + signed-out panel, i18n.

Docs (MkDocs / gh-pages):
- New "External SSO (OIDC)" setup page + reworked "OIDC Refresh Tokens" page
  (Mermaid flows, security model, provider matrix: Keycloak/Authentik/Auth0/
  Google/Azure-Entra/Okta/PogoAlerts).
- OIDC env vars added to the Configuration Reference, enable_oidc/enable_oidc_slo
  to Site Settings, an OIDC troubleshooting section, and nav entries.

Tests: xUnit (session rotation/replay/cap/cleanup over SQLite, provider-agnostic
client, providers/callback) + Jest (token-store single-flight, interceptor
proactive/reactive/loop-guard). Backend 1422 pass, frontend 872 pass.

Author: hokiepokedad2

.env.example

@@ -75,6 +75,49 @@ TELEGRAM_ENABLED=false
 # TELEGRAM_BOT_TOKEN=
 # TELEGRAM_BOT_USERNAME=
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# EXTERNAL SSO / OIDC (optional — delegate login to your own OAuth2/OIDC provider)
+# ═══════════════════════════════════════════════════════════════════════════════
+# Point PoracleWeb at any OAuth2/OIDC provider (e.g. PogoAlerts) for single sign-on.
+# The provider's userinfo endpoint must return a claim holding the user's Poracle id
+# (a Discord/Telegram id) — set OIDC_IDENTITY_CLAIM to that claim name.
+# Enabled is auto-inferred when ClientId + the three URLs are all set; set explicitly to override.
+# OIDC_ENABLED=true
+# OIDC_PROVIDER_NAME=PogoAlerts
+# OIDC_AUTHORIZATION_URL=https://pogoalerts.net/login
+# OIDC_TOKEN_URL=https://pogoalerts.net/api/oauth/token
+# OIDC_USERINFO_URL=https://pogoalerts.net/api/oauth/userinfo
+# OIDC_CLIENT_ID=your_oidc_client_id
+# OIDC_CLIENT_SECRET=your_oidc_client_secret
+# OIDC_SCOPES=openid profile email
+# OIDC_IDENTITY_CLAIM=discord_id
+# OIDC_USERNAME_CLAIM=preferred_username
+# OIDC_AVATAR_CLAIM=picture
+# OIDC_IDENTITY_TYPE=discord:user
+# OIDC_USE_PKCE=true
+#
+# --- Refresh tokens (optional, opt-in) — silent session renewal + revocation propagation ---
+# When OFF (default) the provider's tokens are discarded after login and the internal session
+# JWT lives its full Jwt:ExpirationMinutes (24h); users re-auth at expiry. When ON, PoracleWeb
+# brokers the provider's refresh token SERVER-SIDE (encrypted at rest, never sent to the browser),
+# silently renews the session, and propagates provider-side disable/logout. Requires the provider
+# to actually issue a refresh token. Fully provider-agnostic — see docs/configuration/oidc-refresh-tokens.md.
+# OIDC_USE_REFRESH_TOKENS=true
+# OIDC_ACCESS_TOKEN_MINUTES=30          # internal JWT lifetime for refresh-backed OIDC sessions only
+# OIDC_REFRESH_TOKEN_LIFETIME_DAYS=30   # PoracleWeb-side absolute session cap before a real re-login
+# OIDC_SESSION_REVOKED_RETENTION_DAYS=2 # how long revoked/rotated session rows are kept (replay detection) before cleanup deletes them
+# OIDC_OFFLINE_ACCESS_SCOPE=offline_access  # appended to the authorize scope so the provider issues an RT; empty to disable
+# OIDC_TOKEN_AUTH_METHOD=client_secret_post # client_secret_post (body) | client_secret_basic (HTTP Basic)
+#
+# Per-provider notes (token auth method / offline scope / identity claim):
+#   PogoAlerts : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_post  OIDC_IDENTITY_CLAIM=discord_id
+#   Keycloak   : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_basic  OIDC_IDENTITY_CLAIM=sub
+#   Authentik  : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_post   OIDC_IDENTITY_CLAIM=sub
+#   Auth0      : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_post   OIDC_IDENTITY_CLAIM=sub
+#   Okta       : OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_basic  OIDC_IDENTITY_CLAIM=sub
+#   Azure/Entra: OIDC_OFFLINE_ACCESS_SCOPE=offline_access  OIDC_TOKEN_AUTH_METHOD=client_secret_post   OIDC_IDENTITY_CLAIM=sub
+#   Google     : OIDC_OFFLINE_ACCESS_SCOPE= (empty) and append ?access_type=offline to OIDC_AUTHORIZATION_URL
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # PORACLE API — your running PoracleNG instance
 # ═══════════════════════════════════════════════════════════════════════════════

Applications/Pgan.PoracleWebNet.Api/Configuration/IJwtService.cs

@@ -15,6 +15,13 @@ public interface IJwtService
     /// </summary>
     string GenerateToken(UserInfo user);
 
+    /// <summary>
+    /// Generates a fresh JWT with an explicit lifetime (minutes), overriding the configured
+    /// default. Used for refresh-backed OIDC sessions, which are deliberately short-lived so
+    /// provider-side revocation propagates quickly via silent refresh.
+    /// </summary>
+    string GenerateToken(UserInfo user, int lifetimeMinutes);
+
     /// <summary>
     /// Generates a JWT for an impersonated user. Includes an <c>impersonatedBy</c> claim
     /// identifying the admin who initiated the impersonation.

Applications/Pgan.PoracleWebNet.Api/Configuration/JwtService.cs

@@ -33,6 +33,12 @@ public string GenerateToken(UserInfo user)
         return this.WriteToken(claims);
     }
 
+    public string GenerateToken(UserInfo user, int lifetimeMinutes)
+    {
+        var claims = BuildClaims(user);
+        return this.WriteToken(claims, lifetimeMinutes);
+    }
+
     public string GenerateImpersonationToken(UserInfo user, string impersonatedBy)
     {
         var claims = BuildClaims(user);
@@ -88,7 +94,9 @@ private static List<Claim> BuildClaims(UserInfo user)
         return claims;
     }
 
-    private string WriteToken(List<Claim> claims)
+    private string WriteToken(List<Claim> claims) => this.WriteToken(claims, this._settings.ExpirationMinutes);
+
+    private string WriteToken(List<Claim> claims, int lifetimeMinutes)
     {
         var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(this._settings.Secret));
         var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
@@ -97,7 +105,7 @@ private string WriteToken(List<Claim> claims)
             issuer: this._settings.Issuer,
             audience: this._settings.Audience,
             claims: claims,
-            expires: DateTime.UtcNow.AddMinutes(this._settings.ExpirationMinutes),
+            expires: DateTime.UtcNow.AddMinutes(lifetimeMinutes),
             signingCredentials: credentials);
 
         return new JwtSecurityTokenHandler().WriteToken(token);

Applications/Pgan.PoracleWebNet.Api/Configuration/OidcSettings.cs

@@ -0,0 +1,115 @@
+namespace Pgan.PoracleWebNet.Api.Configuration;
+
+/// <summary>
+/// Configuration for a generic external OIDC / OAuth2 login provider. This lets any
+/// self-hoster delegate PoracleWeb login to their own identity provider (PGAN's
+/// PogoAlerts being one instance). It mirrors the Discord flow, parameterized by config.
+/// All values come from env/appsettings (the provider secret is never stored in the DB);
+/// the admin runtime on/off toggle is the separate <c>enable_oidc</c> site setting.
+/// </summary>
+public class OidcSettings
+{
+    /// <summary>Master switch from server config. When false the provider is hidden regardless of other values.</summary>
+    public bool Enabled { get; set; }
+
+    /// <summary>Display name shown on the login button, e.g. "PogoAlerts".</summary>
+    public string ProviderName { get; set; } = string.Empty;
+
+    /// <summary>Browser-facing authorization endpoint. For PogoAlerts this is e.g. https://pogoalerts.net/login.</summary>
+    public string AuthorizationUrl { get; set; } = string.Empty;
+
+    /// <summary>Token endpoint that exchanges the authorization code for an access token.</summary>
+    public string TokenUrl { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Optional OIDC RP-initiated logout (end-session) endpoint. When set, signing out of
+    /// PoracleWeb redirects the browser here with a <c>post_logout_redirect_uri</c> so the
+    /// provider can also end its own session (true single logout). When empty, logout is
+    /// local-only (the provider session survives). For PogoAlerts this is e.g.
+    /// https://pogoalerts.net/logout.
+    /// </summary>
+    public string EndSessionUrl { get; set; } = string.Empty;
+
+    /// <summary>UserInfo endpoint (OpenID Connect compatible) returning the user's claims.</summary>
+    public string UserInfoUrl { get; set; } = string.Empty;
+
+    public string ClientId { get; set; } = string.Empty;
+    public string ClientSecret { get; set; } = string.Empty;
+
+    /// <summary>Space-delimited OAuth scopes requested at authorization time.</summary>
+    public string Scopes { get; set; } = "openid profile email";
+
+    /// <summary>
+    /// UserInfo claim whose value is the Poracle <c>human</c> id (a Discord or Telegram id).
+    /// Defaults to <c>discord_id</c> (PogoAlerts passes through the linked Discord id);
+    /// falls back to <c>sub</c> when the configured claim is absent.
+    /// </summary>
+    public string IdentityClaim { get; set; } = "discord_id";
+
+    /// <summary>UserInfo claim used as the display username.</summary>
+    public string UsernameClaim { get; set; } = "preferred_username";
+
+    /// <summary>UserInfo claim used as the avatar URL.</summary>
+    public string AvatarClaim { get; set; } = "picture";
+
+    /// <summary>
+    /// Value written to the JWT <c>type</c> claim for users who log in via this provider.
+    /// Defaults to <c>discord:user</c> so downstream admin/role resolution treats the
+    /// passed-through Discord id consistently with a direct Discord login.
+    /// </summary>
+    public string IdentityType { get; set; } = "discord:user";
+
+    /// <summary>Whether to use PKCE (Proof Key for Code Exchange) — recommended and supported by PogoAlerts.</summary>
+    public bool UsePkce { get; set; } = true;
+
+    /// <summary>
+    /// Master opt-in for consuming the provider's refresh token (silent session renewal +
+    /// revocation propagation). Default <c>false</c> — when off, behavior is identical to a
+    /// plain login: the provider's tokens are discarded and the internal JWT lives its full
+    /// <see cref="JwtSettings.ExpirationMinutes"/>. Requires the provider to actually issue a
+    /// refresh token (standard providers gate that behind the <c>offline_access</c> scope —
+    /// see <see cref="OfflineAccessScope"/>).
+    /// </summary>
+    public bool UseRefreshTokens { get; set; }
+
+    /// <summary>
+    /// Internal JWT lifetime (minutes) for refresh-backed OIDC sessions only. Kept short so a
+    /// disable/revocation at the provider propagates within roughly one access-token lifetime.
+    /// Other logins (Discord, Telegram, local, OIDC without refresh) are unaffected and keep
+    /// <see cref="JwtSettings.ExpirationMinutes"/>.
+    /// </summary>
+    public int AccessTokenMinutes { get; set; } = 30;
+
+    /// <summary>
+    /// PoracleWeb-side absolute cap (days) on a refresh session/family before a real re-login is
+    /// forced. Independent of the provider's own refresh-token lifetime; if the provider's token
+    /// expires first, the refresh call fails and the session is revoked — correct either way.
+    /// </summary>
+    public int RefreshTokenLifetimeDays { get; set; } = 30;
+
+    /// <summary>
+    /// How long (days) a revoked/rotated <c>oidc_sessions</c> row is retained before the cleanup
+    /// service deletes it. Revoked rows are kept briefly so a replayed old opaque token is still
+    /// detected (and family-revoked) rather than silently 401ing; replay happens fast, so a short
+    /// window suffices. Kept separate from <see cref="RefreshTokenLifetimeDays"/> so frequent
+    /// rotation doesn't pile up 30 days of dead rows. Expired rows are deleted regardless of this.
+    /// </summary>
+    public int RevokedRetentionDays { get; set; } = 2;
+
+    /// <summary>
+    /// Scope appended to the authorization request (only when <see cref="UseRefreshTokens"/> is on
+    /// and it isn't already present) so a standards-compliant provider issues a refresh token.
+    /// Defaults to <c>offline_access</c>. Set empty for providers that issue refresh tokens
+    /// unconditionally, or that use a non-standard mechanism (e.g. Google's
+    /// <c>access_type=offline</c> appended directly to <see cref="AuthorizationUrl"/>).
+    /// </summary>
+    public string OfflineAccessScope { get; set; } = "offline_access";
+
+    /// <summary>
+    /// How client credentials are presented at the token endpoint: <c>client_secret_post</c>
+    /// (default — credentials in the form body, what PogoAlerts uses) or <c>client_secret_basic</c>
+    /// (HTTP Basic auth header — the default for Keycloak/Okta). Applies to both the
+    /// authorization-code exchange and the refresh-token grant.
+    /// </summary>
+    public string TokenEndpointAuthMethod { get; set; } = "client_secret_post";
+}

Applications/Pgan.PoracleWebNet.Api/Configuration/ServiceCollectionExtensions.cs

@@ -59,6 +59,7 @@ public static IServiceCollection AddPoracleServices(this IServiceCollection serv
         services.AddScoped<IQuickPickDefinitionRepository, QuickPickDefinitionRepository>();
         services.AddScoped<IQuickPickAppliedStateRepository, QuickPickAppliedStateRepository>();
         services.AddScoped<IUserAreaDualWriter, UserAreaDualWriter>();
+        services.AddScoped<IOidcSessionRepository, OidcSessionRepository>();
 
         // Register Services
         services.AddScoped<IMonsterService, MonsterService>();
@@ -149,13 +150,19 @@ public static IServiceCollection AddPoracleServices(this IServiceCollection serv
             }
         });
 
+        // Register the generic OIDC HTTP client (code exchange / refresh / userinfo) and the
+        // server-side refresh-session service (opaque-token rotation + encrypted RT storage).
+        services.AddHttpClient<Services.Oidc.IOidcClient, Services.Oidc.OidcClient>();
+        services.AddScoped<Services.Oidc.IOidcSessionService, Services.Oidc.OidcSessionService>();
+
         // Register JWT service (shared token generation across controllers)
         services.AddSingleton<IJwtService, JwtService>();
 
         // Register settings
         services.Configure<JwtSettings>(configuration.GetSection("Jwt"));
         services.Configure<DiscordSettings>(configuration.GetSection("Discord"));
         services.Configure<TelegramSettings>(configuration.GetSection("Telegram"));
+        services.Configure<OidcSettings>(configuration.GetSection("Oidc"));
         services.Configure<PoracleSettings>(configuration.GetSection("Poracle"));
         services.Configure<KojiSettings>(configuration.GetSection("Koji"));