External SSO / OpenID Connect Login¶

PoracleWeb.NET can delegate login to a generic external OAuth2 / OpenID Connect provider, so users sign in with your own identity provider instead of (or alongside) Discord and Telegram. This page is the comprehensive, provider-agnostic guide to configuring that login flow.

You can ignore OIDC entirely — it is off by default and the sign-in page stays in Local mode (Discord / Telegram). Turn it on only when you want to point PoracleWeb at a provider.

Silent session renewal and refresh-token handling are documented separately on the OIDC Refresh Tokens page — this page covers the login itself.

How it works¶

The flow is the standard OAuth2 authorization-code grant (with PKCE by default):

sequenceDiagram
  participant B as Browser
  participant P as PoracleWeb API
  participant I as Provider (IdP)
  B->>P: GET /api/auth/oidc/login
  P->>B: 302 to provider authorize (state cookie, PKCE S256)
  B->>I: authorize → sign in / consent
  I->>B: 302 /api/auth/oidc/callback?code&state
  B->>P: callback(code, state)
  P->>P: validate state (CSRF) + PKCE verifier
  P->>I: POST /token (grant=authorization_code)
  I-->>P: { access_token, ... }
  P->>I: GET /userinfo (Bearer access_token)
  I-->>P: { identity claim, username, avatar }
  P->>P: resolve human → check enabled + roles + enable_oidc gate
  P->>B: 302 /auth/oidc/callback#token=JWT

• CSRF: a random state value is stored in an HttpOnly cookie and verified on callback.
• PKCE: when OIDC_USE_PKCE=true (default), a code verifier is stored in an HttpOnly cookie and only the S256 challenge is sent to the provider.
• Redirect URI: PoracleWeb always uses {your-host}/api/auth/oidc/callback. Register exactly this URI at your provider.
• Identity resolution: the configured identity claim (falling back to sub) is looked up against the Poracle human table. The provider authenticates; Poracle authorizes.
• JWT type claim: successful logins mint PoracleWeb's internal JWT with the type claim set to OIDC_IDENTITY_TYPE (default discord:user), so admin/role resolution treats the passed-through Discord id consistently with a direct Discord login.

Step-by-step setup¶

1. Register a client at your identity provider. Create an OAuth2 / OIDC application and set its redirect (callback) URI to:

{your-host}/api/auth/oidc/callback

for example https://poracle.example.com/api/auth/oidc/callback. Note the client id and client secret. Enable PKCE if your provider supports it (recommended).

1. Configure the OIDC_* variables in your .env (see the reference table). At minimum you need the three endpoint URLs, the client id, the client secret, and — unless your provider's sub claim already holds the Poracle id — OIDC_IDENTITY_CLAIM. Restart PoracleWeb so the server config takes effect.

2. Switch the sign-in mode to SSO. In Admin → Settings → Authentication, flip the Local ⇄ SSO segmented switch to SSO. This is the runtime opt-in (enable_oidc=true) and is gated on OIDC being fully configured plus a confirmation dialog. See Auth mode below.

Login configuration reference¶

All variables are read from .env (or the Oidc__* .NET convention) and require a restart to take effect. The provider secret is never stored in the database and is only ever returned masked.

The refresh-token variables (OIDC_USE_REFRESH_TOKENS, OIDC_ACCESS_TOKEN_MINUTES, OIDC_OFFLINE_ACCESS_SCOPE, OIDC_TOKEN_AUTH_METHOD, …) are documented on the OIDC Refresh Tokens page. See also the full Configuration Reference.

Auth mode (Local vs SSO)¶

The admin Authentication panel exposes a single segmented Local ⇄ SSO switch backed by the one runtime site setting enable_oidc:

• OIDC is opt-in. Unlike Discord/Telegram (where an absent setting means enabled), SSO is only active when enable_oidc is explicitly true. The default sign-in mode is always Local.
• Switching to SSO is gated on OIDC being fully configured and a confirmation dialog, to prevent locking yourself out against a misconfigured provider.
• In SSO mode the Discord and Telegram sections of the Authentication panel are hidden, replaced by the read-only OIDC config card (from /api/settings/oidc-config, secrets masked), the single-logout toggle (when an end-session URL is set), and the silent-refresh toggle (when refresh is configured — see the refresh page).

Login page behavior¶

• When SSO is active, the login page auto-redirects to your provider so users aren't shown an unnecessary intermediate screen.
• /login?loggedout=1 shows a "Signed out" panel and suppresses the auto-redirect, so a user who just logged out isn't immediately re-logged-in. The single-logout flow redirects here.
• The /api/auth/providers endpoint drives the login UI. Its oidc block reports: configured, enabledByAdmin, providerName, endSession (whether SLO is available), and refresh (whether silent refresh is wired up).

Single logout (SLO)¶

When OIDC_END_SESSION_URL is set, signing out can also end the user's session at the provider (RP-initiated logout), not just locally. GET /api/auth/oidc/logout bounces the browser to the provider's end-session endpoint with a post_logout_redirect_uri of {origin}/login?loggedout=1, then returns to the signed-out panel.

Single logout requires both:

1. OIDC_END_SESSION_URL configured, and
2. the runtime toggle enable_oidc_slo not set to false (absent = on once the URL is wired).

If either is missing, logout falls back to local-only — PoracleWeb clears its own session but the provider session survives.

Break-glass (AUTH_FORCE_LOCAL)¶

AUTH_FORCE_LOCAL=true (Auth__ForceLocal) forces the local login page regardless of the SSO mode. It is a recovery mechanism: if an admin switches to SSO against a provider that is down or misconfigured and everyone is locked out, set this env flag and restart to get the local Discord / Telegram login back without touching the database.

It overrides enable_oidc for the /api/auth/providers response (OIDC reports enabledByAdmin=false while it is set). The admin OIDC config card surfaces a forceLocal flag so the UI can explain why OIDC appears inactive even when enabled.

Error codes¶

On any failure the browser is redirected to /login#error=CODE. The login page maps these to a message.

The not_in_guild / missing_required_role / role_check_failed codes only apply when role-based access (enable_roles) is configured and the identity is a Discord id — they are shared verbatim with the Discord login path.

Endpoints¶

POST /api/auth/oidc/refresh and /refresh/revoke belong to the silent-renewal feature — see the OIDC Refresh Tokens page.

Provider matrix¶

For login, the per-provider differences come down to the identity claim. (If you also enable refresh tokens, the token-endpoint auth method and offline-access scope also matter — those columns are included for convenience.)

† Only relevant if you also enable refresh tokens. For plain login, these are ignored.

Copy-paste login snippets for the most common providers (replace the example URLs with your provider's actual endpoints):

Keycloak¶

OIDC_PROVIDER_NAME=Keycloak
OIDC_AUTHORIZATION_URL=https://kc.example.com/realms/poracle/protocol/openid-connect/auth
OIDC_TOKEN_URL=https://kc.example.com/realms/poracle/protocol/openid-connect/token
OIDC_USERINFO_URL=https://kc.example.com/realms/poracle/protocol/openid-connect/userinfo
OIDC_END_SESSION_URL=https://kc.example.com/realms/poracle/protocol/openid-connect/logout
OIDC_CLIENT_ID=poracleweb
OIDC_CLIENT_SECRET=your_client_secret
OIDC_SCOPES=openid profile email
OIDC_IDENTITY_CLAIM=sub
OIDC_USE_PKCE=true

Auth0¶

OIDC_PROVIDER_NAME=Auth0
OIDC_AUTHORIZATION_URL=https://your-tenant.us.auth0.com/authorize
OIDC_TOKEN_URL=https://your-tenant.us.auth0.com/oauth/token
OIDC_USERINFO_URL=https://your-tenant.us.auth0.com/userinfo
OIDC_END_SESSION_URL=https://your-tenant.us.auth0.com/oidc/logout
OIDC_CLIENT_ID=your_client_id
OIDC_CLIENT_SECRET=your_client_secret
OIDC_SCOPES=openid profile email
OIDC_IDENTITY_CLAIM=sub
OIDC_USE_PKCE=true

For Google, Azure AD / Entra, and Okta, use the same shape — set the three endpoint URLs and the identity claim from the matrix above. Google needs ?access_type=offline appended to OIDC_AUTHORIZATION_URL only if you go on to enable refresh tokens.

Next: silent session renewal¶

By default PoracleWeb mints a short-lived internal JWT and discards the provider's tokens at login. To keep sessions alive in the background and propagate provider-side disable/logout to PoracleWeb, enable refresh-token consumption:

➡️ OIDC Refresh Tokens — opt-in silent renewal, revocation propagation, the provider config matrix for refresh, and the security model.

Related pages¶

• Configuration Reference — the full OIDC_* variable list and every other env var.
• Site Settings — the enable_oidc and enable_oidc_slo runtime toggles.
• Discord OAuth — the login flow SSO mirrors, and the source of the reused role-gating error codes.