webgate 2.6.0__tar.gz → 2.7.0__tar.gz

{webgate-2.6.0 → webgate-2.7.0}/.github/workflows/demo.yml

@@ -4,8 +4,10 @@ name: Deploy demo
 # it spent months serving a version several releases behind the repository.
 
 on:
-  release:
-    types: [published]
+  # Called by release.yml rather than triggered by the release it creates: GitHub
+  # does not start workflows from events raised with GITHUB_TOKEN, so a
+  # `release: published` trigger here never fires and the demo silently stays behind.
+  workflow_call:
   workflow_dispatch:
 
 permissions:

{webgate-2.6.0 → webgate-2.7.0}/.github/workflows/release.yml

@@ -121,3 +121,8 @@ jobs:
           tag_name: ${{ inputs.tag || github.ref_name }}
           name: v${{ needs.verify.outputs.version }}
           body_path: notes.md
+
+  demo:
+    needs: github_release
+    uses: ./.github/workflows/demo.yml
+    secrets: inherit

{webgate-2.6.0 → webgate-2.7.0}/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## v2.7.0 (2026-09-17) — single sign-on
+
+LDAP already existed, but no company running Entra ID, Okta or Google Workspace is
+going to keep a second directory for one tool. It was the first thing anyone asked
+about, and the thing most likely to decide whether webgate gets deployed at all.
+
+### Single sign-on (OpenID Connect)
+
+**Admin → Settings → Single sign-on**, alongside local accounts and LDAP rather than
+instead of them. Register one redirect URI with your provider, fill in the issuer,
+client ID, secret and scopes, and everything else — the endpoints, the signing keys —
+comes from the provider's discovery document.
+
+- **The ID token is actually verified**: signature against the provider's published
+  keys, plus issuer, audience, expiry, and a nonce tied to that one sign-in, so a token
+  captured from another flow cannot be replayed into this one. A token that merely
+  decodes proves nothing.
+- **Authorization code with PKCE**, so it is safe with or without a client secret.
+- **The in-progress sign-in lives in the database**, not in worker memory. The browser
+  can come back to a different worker than the one it left, which is the whole point of
+  the stateless design.
+- **The session token never travels in a URL.** The callback hands the page a one-time
+  code, good for about a minute, which it trades for a session — so nothing sensitive
+  reaches browser history or a proxy log.
+- **A provider group grants nothing until an admin maps it**, exactly as LDAP works. A
+  directory group created next month cannot quietly open a webgate group that happens
+  to share its name. A separate admin-groups list grants admin.
+- Sign-ins are audited as `sso_login`, with the groups granted.
+- Accounts created this way have **no local password** — nothing to reset, nothing to
+  leak.
+
+Twenty-one tests, run against a real identity provider started for the test: it
+publishes a discovery document and a JWKS and signs its own tokens, so the
+verification is exercised rather than mocked away. A token signed with the wrong key,
+issued for another audience, expired, or carrying another sign-in's nonce is refused,
+and each of those is a test.
+
+[Setup, and what to do when nobody gets any groups](https://kalexnolasco.github.io/webgate/guide/sso/).
+
+354 tests: 345 unit, 9 browser.
+
+---
+
 ## v2.6.0 (2026-09-16) — rotating the secret key no longer breaks everything
 
 ### Fixed

{webgate-2.6.0 → webgate-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: webgate
-Version: 2.6.0
+Version: 2.7.0
 Summary: Self-hosted web application for remote server management via SSH terminal and SFTP file browser
 Project-URL: Homepage, https://github.com/kalexnolasco/webgate
 Project-URL: Documentation, https://kalexnolasco.github.io/webgate/
@@ -189,7 +189,7 @@ flowchart TB
 | **SFTP** | Full file ops + drag & drop upload, **sortable columns**, **multi-select** with batch ZIP download and delete, hidden-file toggle, in-browser editor (CodeMirror 6), PDF/image preview |
 | **Server Registry** | Groups, tags, password/key auth, encrypted at rest (Fernet), **verified host keys** (TOFU), **favourites and recents**, import/export JSON, **jump host / bastion** chaining |
 | **Access Control** | Admin/user roles, per-server SSH/SFTP toggles, SFTP path restrictions, read-only SFTP mode, group-based visibility |
-| **Auth** | JWT + bcrypt locally, **2FA TOTP**, **API keys** for automation, **LDAP / Active Directory** with group→role mapping |
+| **Auth** | **Single sign-on (OpenID Connect)** — Entra ID, Okta, Google Workspace, Keycloak — with group→role mapping, plus JWT + bcrypt locally, **2FA TOTP**, **API keys** for automation, **LDAP / Active Directory** |
 | **Compliance** | **Session recording** to asciinema cast files with browser replay, off by default and opted into per server, **audit log** covering every SFTP operation, registry and account change, searchable by filename, **webhooks** (HMAC-signed) on key events |
 | **Migration** | **Full-state backup and restore** — servers with credentials, users, groups, webhooks and API keys in one passphrase-encrypted file, portable between instances |
 | **AI agent** | Per-server iterative chat over **Ollama** or **OpenRouter**, read-only inspection tools, **works on SFTP-only hosts**, cached results and searchable findings — configured in the admin panel, off until then |
@@ -727,6 +727,7 @@ The demo middleware blocks all writes on `/api/*` (login, terminal share and tot
 | **Servers** | `GET/POST/PUT/DELETE /api/servers`, `POST /api/servers/{id}/test`, `GET /api/servers/groups`, `POST /api/servers/import`, `GET /api/servers/export`, `GET /api/servers/status` |
 | **Terminal** | `WS /api/ws/terminal/{server_id}` (owner), `WS /api/ws/terminal/quick` (one-off), `WS /api/ws/terminal/join/{token}?mode=rw\|ro` (joiner), `POST/DELETE /api/terminal/share/{session_id}` |
 | **Files (SFTP)** | `GET /ls`, `GET /read`, `GET /download`, `GET /download-zip` (one directory), `POST /download-zip` (a chosen selection), `POST /upload`, `PUT /write`, `POST /mkdir`, `POST /rename`, `DELETE /delete`, `POST /chmod`, `GET /stat` (all under `/api/files/{server_id}/`) |
+| **Single sign-on** | `GET /api/auth/sso/start`, `GET /api/auth/sso/callback`, `POST /api/auth/sso/exchange` |
 | **Settings** | `GET /api/settings`, `PUT /api/settings`, `POST /api/settings/reset` (admin only) |
 | **Agent** | `GET/PUT /api/agent/settings`, `POST /api/agent/models`, `POST /api/agent/chat/{server_id}`, `GET/DELETE /api/agent/conversations/{server_id}`, `GET /api/agent/findings` |
 | **Branding** | `GET /api/branding` (public), `PUT/DELETE /api/branding` (admin only) |
@@ -790,6 +791,7 @@ docker compose -f compose.dev.yml up --build
 
 ## Security
 
+- **Single sign-on** verifies the ID token properly: signature against the provider's published keys, plus issuer, audience, expiry and a per-sign-in nonce. The flow uses PKCE, its state lives in the database so it works across workers, and the session token is handed over as a one-time code rather than in a URL
 - **Host keys are verified** — trust on first use. The first connection to a server records the key it presents; every connection after that is checked against it *before authentication runs*, so a mismatch sends nothing. Accepting a changed key is a deliberate, audited admin action. This covers the terminal, SFTP, the connection pool, the status monitor, the agent and jump hosts
 - All SSH passwords and private keys are encrypted at rest with **Fernet** (key derived from `WEBGATE_SECRET_KEY`)
 - **The default secret key is refused.** That key signs every session token and derives the credential encryption key, and its default is published in this repository — a deployment that never changed it will hand a valid admin token to anyone who asks. webgate now stops at startup rather than serving under it, unless it is bound to loopback only

{webgate-2.6.0 → webgate-2.7.0}/README.md

@@ -140,7 +140,7 @@ flowchart TB
 | **SFTP** | Full file ops + drag & drop upload, **sortable columns**, **multi-select** with batch ZIP download and delete, hidden-file toggle, in-browser editor (CodeMirror 6), PDF/image preview |
 | **Server Registry** | Groups, tags, password/key auth, encrypted at rest (Fernet), **verified host keys** (TOFU), **favourites and recents**, import/export JSON, **jump host / bastion** chaining |
 | **Access Control** | Admin/user roles, per-server SSH/SFTP toggles, SFTP path restrictions, read-only SFTP mode, group-based visibility |
-| **Auth** | JWT + bcrypt locally, **2FA TOTP**, **API keys** for automation, **LDAP / Active Directory** with group→role mapping |
+| **Auth** | **Single sign-on (OpenID Connect)** — Entra ID, Okta, Google Workspace, Keycloak — with group→role mapping, plus JWT + bcrypt locally, **2FA TOTP**, **API keys** for automation, **LDAP / Active Directory** |
 | **Compliance** | **Session recording** to asciinema cast files with browser replay, off by default and opted into per server, **audit log** covering every SFTP operation, registry and account change, searchable by filename, **webhooks** (HMAC-signed) on key events |
 | **Migration** | **Full-state backup and restore** — servers with credentials, users, groups, webhooks and API keys in one passphrase-encrypted file, portable between instances |
 | **AI agent** | Per-server iterative chat over **Ollama** or **OpenRouter**, read-only inspection tools, **works on SFTP-only hosts**, cached results and searchable findings — configured in the admin panel, off until then |
@@ -678,6 +678,7 @@ The demo middleware blocks all writes on `/api/*` (login, terminal share and tot
 | **Servers** | `GET/POST/PUT/DELETE /api/servers`, `POST /api/servers/{id}/test`, `GET /api/servers/groups`, `POST /api/servers/import`, `GET /api/servers/export`, `GET /api/servers/status` |
 | **Terminal** | `WS /api/ws/terminal/{server_id}` (owner), `WS /api/ws/terminal/quick` (one-off), `WS /api/ws/terminal/join/{token}?mode=rw\|ro` (joiner), `POST/DELETE /api/terminal/share/{session_id}` |
 | **Files (SFTP)** | `GET /ls`, `GET /read`, `GET /download`, `GET /download-zip` (one directory), `POST /download-zip` (a chosen selection), `POST /upload`, `PUT /write`, `POST /mkdir`, `POST /rename`, `DELETE /delete`, `POST /chmod`, `GET /stat` (all under `/api/files/{server_id}/`) |
+| **Single sign-on** | `GET /api/auth/sso/start`, `GET /api/auth/sso/callback`, `POST /api/auth/sso/exchange` |
 | **Settings** | `GET /api/settings`, `PUT /api/settings`, `POST /api/settings/reset` (admin only) |
 | **Agent** | `GET/PUT /api/agent/settings`, `POST /api/agent/models`, `POST /api/agent/chat/{server_id}`, `GET/DELETE /api/agent/conversations/{server_id}`, `GET /api/agent/findings` |
 | **Branding** | `GET /api/branding` (public), `PUT/DELETE /api/branding` (admin only) |
@@ -741,6 +742,7 @@ docker compose -f compose.dev.yml up --build
 
 ## Security
 
+- **Single sign-on** verifies the ID token properly: signature against the provider's published keys, plus issuer, audience, expiry and a per-sign-in nonce. The flow uses PKCE, its state lives in the database so it works across workers, and the session token is handed over as a one-time code rather than in a URL
 - **Host keys are verified** — trust on first use. The first connection to a server records the key it presents; every connection after that is checked against it *before authentication runs*, so a mismatch sends nothing. Accepting a changed key is a deliberate, audited admin action. This covers the terminal, SFTP, the connection pool, the status monitor, the agent and jump hosts
 - All SSH passwords and private keys are encrypted at rest with **Fernet** (key derived from `WEBGATE_SECRET_KEY`)
 - **The default secret key is refused.** That key signs every session token and derives the credential encryption key, and its default is published in this repository — a deployment that never changed it will hand a valid admin token to anyone who asks. webgate now stops at startup rather than serving under it, unless it is bound to loopback only

{webgate-2.6.0 → webgate-2.7.0}/ROADMAP.md

@@ -96,6 +96,11 @@ Tracks the development plan for **webgate**. Items are organized by release.
 - [x] **A per-account cap on concurrent SSH sessions**
 - [x] **The demo banner no longer covers the interface**, and every diagram in the repository renders legibly on both GitHub grounds
 
+### v2.7.0 — Single sign-on (2026-09-17)
+- [x] **OpenID Connect sign-on** for Entra ID, Okta, Google Workspace, Keycloak and Authentik, with the ID token verified against the provider's keys and a per-sign-in nonce
+- [x] **Provider groups map to webgate groups**, and an unmapped group grants nothing
+- [x] **The session token is handed over as a one-time code**, never in a URL
+
 ---
 
 ## Planned

webgate-2.7.0/VERSION

@@ -0,0 +1 @@
+2.7.0

{webgate-2.6.0 → webgate-2.7.0}/docs/changelog.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## v2.7.0 (2026-09-17) — single sign-on
+
+LDAP already existed, but no company running Entra ID, Okta or Google Workspace is
+going to keep a second directory for one tool. It was the first thing anyone asked
+about, and the thing most likely to decide whether webgate gets deployed at all.
+
+### Single sign-on (OpenID Connect)
+
+**Admin → Settings → Single sign-on**, alongside local accounts and LDAP rather than
+instead of them. Register one redirect URI with your provider, fill in the issuer,
+client ID, secret and scopes, and everything else — the endpoints, the signing keys —
+comes from the provider's discovery document.
+
+- **The ID token is actually verified**: signature against the provider's published
+  keys, plus issuer, audience, expiry, and a nonce tied to that one sign-in, so a token
+  captured from another flow cannot be replayed into this one. A token that merely
+  decodes proves nothing.
+- **Authorization code with PKCE**, so it is safe with or without a client secret.
+- **The in-progress sign-in lives in the database**, not in worker memory. The browser
+  can come back to a different worker than the one it left, which is the whole point of
+  the stateless design.
+- **The session token never travels in a URL.** The callback hands the page a one-time
+  code, good for about a minute, which it trades for a session — so nothing sensitive
+  reaches browser history or a proxy log.
+- **A provider group grants nothing until an admin maps it**, exactly as LDAP works. A
+  directory group created next month cannot quietly open a webgate group that happens
+  to share its name. A separate admin-groups list grants admin.
+- Sign-ins are audited as `sso_login`, with the groups granted.
+- Accounts created this way have **no local password** — nothing to reset, nothing to
+  leak.
+
+Twenty-one tests, run against a real identity provider started for the test: it
+publishes a discovery document and a JWKS and signs its own tokens, so the
+verification is exercised rather than mocked away. A token signed with the wrong key,
+issued for another audience, expired, or carrying another sign-in's nonce is refused,
+and each of those is a test.
+
+[Setup, and what to do when nobody gets any groups](https://kalexnolasco.github.io/webgate/guide/sso/).
+
+354 tests: 345 unit, 9 browser.
+
+---
+
 ## v2.6.0 (2026-09-16) — rotating the secret key no longer breaks everything
 
 ### Fixed

webgate-2.7.0/docs/guide/sso.md

@@ -0,0 +1,83 @@
+# Single sign-on
+
+**Admin → Settings → Single sign-on.** OpenID Connect, which is what Entra ID, Okta,
+Google Workspace, Keycloak and Authentik all speak.
+
+LDAP still works, and so do local accounts. Turning this on adds a button to the
+sign-in screen; it does not take anything away.
+
+## What to register with your provider
+
+One redirect URI:
+
+```
+https://your-webgate/api/auth/sso/callback
+```
+
+Then fill in four things here: the **issuer URL**, the **client ID**, the **client
+secret** if your provider issued one, and the **scopes**. Everything else — the
+authorize and token endpoints, the signing keys — is read from
+`{issuer}/.well-known/openid-configuration`, so there is nothing else to copy across.
+
+| Provider | Issuer looks like |
+|---|---|
+| Entra ID | `https://login.microsoftonline.com/<tenant-id>/v2.0` |
+| Okta | `https://<org>.okta.com/oauth2/default` |
+| Google Workspace | `https://accounts.google.com` |
+| Keycloak | `https://<host>/realms/<realm>` |
+| Authentik | `https://<host>/application/o/<slug>/` |
+
+!!! tip "Behind a proxy that rewrites the host"
+    webgate works out its own address from the request. If a proxy changes it, set
+    **Public URL** and the redirect will be that plus `/api/auth/sso/callback`.
+
+## Groups decide what people can reach
+
+A group from your directory means nothing here until an admin maps it:
+
+```json
+{"infra-oncall": "prod", "platform": "core"}
+```
+
+An unmapped group grants nothing. That is deliberate: a directory group created next
+month must not quietly open a webgate group that happens to share its name.
+
+**Admin groups** is a separate list — membership in any of them makes the person a
+webgate admin, and admins see every server.
+
+Both are re-read on every sign-in, so removing somebody from a group in your directory
+takes effect the next time they sign in. It does not end a session already open; the
+session-token lifetime under **Security** decides that.
+
+### If nobody gets any groups
+
+Your provider is probably not sending the claim. Two things to check: the **scopes**
+usually need an extra one (`groups` on Okta and Keycloak, `GroupMember.Read.All`
+consented on Entra), and the **groups claim** has to match the name your provider
+uses. Entra sends group *object ids* by default rather than names, unless the app
+registration is set to emit names.
+
+## What happens on sign-in
+
+1. The button sends the browser to your provider, with PKCE and a one-time `state` and
+   `nonce`.
+2. Your provider sends it back to the callback with a code.
+3. webgate exchanges the code, then **verifies the ID token** — signature against your
+   provider's published keys, issuer, audience, expiry, and that the nonce matches the
+   one it issued for this sign-in.
+4. The account is created or refreshed, with the groups from the mapping.
+5. The browser is handed a **one-time code**, and trades it for a session. The session
+   token is never put in a URL, so it cannot end up in browser history or a proxy log.
+
+The in-progress sign-in lives in the database, not in memory, so the browser can come
+back to a different worker than the one it left. Abandoned attempts are cleared after
+ten minutes.
+
+## Notes
+
+- A person who signs in this way has **no local password**. There is nothing to reset
+  and nothing to leak; your provider is the credential.
+- 2FA is your provider's business here. webgate's own TOTP applies to local accounts.
+- Every sign-in is recorded as `sso_login` in the audit log, with the groups granted.
+- Turning SSO off leaves the accounts it created. They simply have no working password
+  until an admin sets one.

{webgate-2.6.0 → webgate-2.7.0}/mkdocs.yml

@@ -46,6 +46,7 @@ nav:
     - Split View: guide/split.md
     - User Management: guide/users.md
     - Access model (groups, LDAP, tags): guide/access-control.md
+    - Single sign-on (OIDC): guide/sso.md
     - Advanced (jump host, snippets, sharing, recording): guide/advanced.md
     - Integrations (webhooks, LDAP, API keys, reverse proxy): guide/integrations.md
     - Settings (admin panel): guide/settings.md

{webgate-2.6.0 → webgate-2.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webgate"
-version = "2.6.0"
+version = "2.7.0"
 description = "Self-hosted web application for remote server management via SSH terminal and SFTP file browser"
 readme = "README.md"
 license = "MIT"

{webgate-2.6.0 → webgate-2.7.0}/src/webgate/app.py

@@ -13,6 +13,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from webgate import __version__
 from webgate.agent.routes import router as agent_router
 from webgate.agent.store import load_config
+from webgate.auth import oidc
 from webgate.auth.routes import limiter
 from webgate.auth.routes import router as auth_router
 from webgate.auth.service import seed_admin
@@ -95,7 +96,13 @@ def create_app() -> FastAPI:
         agent_available = False
         if not settings.demo_mode:
             agent_available = (await load_config(session)).enabled
-        return {"demo_mode": settings.demo_mode, "agent_available": agent_available}
+        return {
+            "demo_mode": settings.demo_mode,
+            "agent_available": agent_available,
+            # The sign-in screen needs this before anyone has authenticated.
+            "sso_enabled": oidc.enabled(),
+            "sso_name": oidc.provider_name() if oidc.enabled() else "",
+        }
 
     if settings.demo_mode:
         # In demo mode block any state-changing request on /api/* except an

{webgate-2.6.0 → webgate-2.7.0}/src/webgate/auth/models.py

@@ -77,6 +77,10 @@ class UserUpdateGroups(BaseModel):
     allowed_groups: list[str]
 
 
+class SsoExchange(BaseModel):
+    code: str
+
+
 class ChangePassword(BaseModel):
     new_password: str
 

webgate-2.7.0/src/webgate/auth/oidc.py

@@ -0,0 +1,278 @@
+"""Single sign-on over OpenID Connect.
+
+LDAP already existed, but no company running Entra ID, Okta or Google Workspace is
+going to keep a second directory for one tool. This is the authorization code flow
+with PKCE, which every one of those providers speaks.
+
+Two things shape the implementation:
+
+* **The gateway may be several workers.** The state, nonce and PKCE verifier are
+  written to the database, not held in memory, because the browser can come back to a
+  different worker than the one it left. The same table carries the one-time code the
+  callback hands the page, so the session token never appears in a URL, in browser
+  history or in a proxy log.
+* **An ID token is only worth what its verification is worth.** The signature is
+  checked against the provider's published keys, and the issuer, audience, expiry and
+  nonce are all checked too. A token that merely decodes proves nothing.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import secrets
+import time
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+from jose import jwt
+from sqlalchemy import DateTime, String, Text, delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Mapped, mapped_column
+
+from webgate.db.engine import Base
+from webgate.runtime_config import store as runtime
+
+logger = logging.getLogger(__name__)
+
+# A sign-in that takes longer than this was abandoned, and the row is a stale secret.
+FLOW_TTL = timedelta(minutes=10)
+# The handover code is used within a second of being issued; a minute is generous.
+CODE_TTL = timedelta(minutes=1)
+DISCOVERY_TTL = 3600.0
+
+
+class OidcError(Exception):
+    """Something the operator or the provider has to fix, phrased for whoever sees it."""
+
+
+class OidcFlow(Base):
+    """One sign-in attempt, in progress.
+
+    In the database rather than in memory so the callback can land on any worker,
+    which is the whole point of the stateless design.
+    """
+
+    __tablename__ = "oidc_flows"
+
+    state: Mapped[str] = mapped_column(String(64), primary_key=True)
+    nonce: Mapped[str] = mapped_column(String(64))
+    verifier: Mapped[str] = mapped_column(String(128))
+    redirect_uri: Mapped[str] = mapped_column(Text, default="")
+    # Set once the provider has been believed: the page trades this for a session.
+    handover: Mapped[str] = mapped_column(String(64), default="")
+    user_id: Mapped[int | None] = mapped_column(nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=lambda: datetime.now(UTC))
+
+
+_discovery: dict[str, tuple[float, dict[str, Any]]] = {}
+_jwks: dict[str, tuple[float, dict[str, Any]]] = {}
+
+
+def enabled() -> bool:
+    return bool(runtime.get("oidc_enabled") and runtime.get("oidc_issuer"))
+
+
+def provider_name() -> str:
+    """What the button on the sign-in screen should say."""
+    return str(runtime.get("oidc_display_name") or "").strip() or "single sign-on"
+
+
+def _b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+async def _fetch(url: str, cache: dict[str, tuple[float, dict[str, Any]]]) -> dict[str, Any]:
+    hit = cache.get(url)
+    if hit and time.monotonic() - hit[0] < DISCOVERY_TTL:
+        return hit[1]
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            resp = await client.get(url)
+            resp.raise_for_status()
+            data: dict[str, Any] = resp.json()
+    except Exception as exc:
+        raise OidcError(f"Could not reach the identity provider at {url}: {exc}") from exc
+    cache[url] = (time.monotonic(), data)
+    return data
+
+
+async def discover() -> dict[str, Any]:
+    issuer = str(runtime.get("oidc_issuer")).rstrip("/")
+    return await _fetch(f"{issuer}/.well-known/openid-configuration", _discovery)
+
+
+async def begin(session: AsyncSession, redirect_uri: str) -> str:
+    """Record a new sign-in attempt and return the URL to send the browser to."""
+    if not enabled():
+        raise OidcError("Single sign-on is not configured on this gateway")
+
+    config = await discover()
+    verifier = _b64url(secrets.token_bytes(64))
+    challenge = _b64url(hashlib.sha256(verifier.encode()).digest())
+    flow = OidcFlow(
+        state=secrets.token_urlsafe(32),
+        nonce=secrets.token_urlsafe(24),
+        verifier=verifier,
+        redirect_uri=redirect_uri,
+    )
+    session.add(flow)
+    # Abandoned attempts are stale secrets; clear them out on the way past.
+    await session.execute(
+        delete(OidcFlow).where(OidcFlow.created_at < datetime.now(UTC) - FLOW_TTL)
+    )
+    await session.commit()
+
+    query = {
+        "response_type": "code",
+        "client_id": str(runtime.get("oidc_client_id")),
+        "redirect_uri": redirect_uri,
+        "scope": str(runtime.get("oidc_scopes")) or "openid profile email",
+        "state": flow.state,
+        "nonce": flow.nonce,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    }
+    return f"{config['authorization_endpoint']}?{urlencode(query)}"
+
+
+async def _claims(code: str, flow: OidcFlow) -> dict[str, Any]:
+    """Trade the code for an ID token, and believe it only once it checks out."""
+    config = await discover()
+    data = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": flow.redirect_uri,
+        "client_id": str(runtime.get("oidc_client_id")),
+        "code_verifier": flow.verifier,
+    }
+    secret = str(runtime.get("oidc_client_secret"))
+    if secret:
+        data["client_secret"] = secret
+
+    try:
+        async with httpx.AsyncClient(timeout=15) as client:
+            resp = await client.post(config["token_endpoint"], data=data)
+    except Exception as exc:
+        raise OidcError(f"Could not reach the provider's token endpoint: {exc}") from exc
+    if resp.status_code >= 400:
+        detail = resp.text[:200]
+        raise OidcError(f"The provider rejected the sign-in ({resp.status_code}): {detail}")
+
+    id_token = resp.json().get("id_token")
+    if not id_token:
+        raise OidcError("The provider returned no id_token; check that the scope includes openid")
+
+    jwks = await _fetch(config["jwks_uri"], _jwks)
+    try:
+        claims: dict[str, Any] = jwt.decode(
+            id_token,
+            jwks,
+            algorithms=config.get("id_token_signing_alg_values_supported") or ["RS256"],
+            audience=str(runtime.get("oidc_client_id")),
+            issuer=config.get("issuer") or str(runtime.get("oidc_issuer")).rstrip("/"),
+        )
+    except Exception as exc:
+        raise OidcError(f"The provider's token did not verify: {exc}") from exc
+
+    # Without this a token minted for another sign-in could be replayed into this one.
+    if claims.get("nonce") != flow.nonce:
+        raise OidcError("The provider's token was issued for a different sign-in")
+    return claims
+
+
+def _as_list(raw: object) -> list[str]:
+    if isinstance(raw, str):
+        return [raw]
+    if isinstance(raw, list):
+        return [str(x) for x in raw]  # pyright: ignore[reportUnknownArgumentType]
+    return []
+
+
+def identity(claims: dict[str, Any]) -> tuple[str, list[str], bool]:
+    """Username, webgate groups, and whether they are an admin.
+
+    Group names come from the provider and mean nothing here until an admin maps
+    them, exactly as LDAP works -- so a new directory group cannot silently grant
+    access to a server group of the same name.
+    """
+    username = str(
+        claims.get(str(runtime.get("oidc_username_claim")))
+        or claims.get("preferred_username")
+        or claims.get("email")
+        or claims.get("sub")
+        or ""
+    ).strip()
+    if not username:
+        raise OidcError(
+            "The provider's token carried no username. Set the username claim in "
+            "Admin -> Settings -> Single sign-on to one your provider sends."
+        )
+
+    from_provider = _as_list(claims.get(str(runtime.get("oidc_groups_claim"))))
+    try:
+        mapping: dict[str, str] = json.loads(str(runtime.get("oidc_group_map")) or "{}")
+    except json.JSONDecodeError:
+        logger.warning("The SSO group mapping is not valid JSON; treating it as empty")
+        mapping = {}
+    try:
+        admin_groups = set(json.loads(str(runtime.get("oidc_admin_groups")) or "[]"))
+    except json.JSONDecodeError:
+        admin_groups = set()
+
+    groups = sorted({mapping[g] for g in from_provider if g in mapping})
+    return username, groups, bool(admin_groups & set(from_provider))
+
+
+async def take_flow(session: AsyncSession, state: str) -> OidcFlow:
+    """The recorded attempt for this state, consumed so it cannot be replayed."""
+    flow = (
+        await session.execute(select(OidcFlow).where(OidcFlow.state == state))
+    ).scalar_one_or_none()
+    if flow is None:
+        raise OidcError(
+            "This sign-in is no longer valid. It may have been completed already, or "
+            "taken too long. Start again."
+        )
+    if datetime.now(UTC) - flow.created_at.replace(tzinfo=UTC) > FLOW_TTL:
+        await session.delete(flow)
+        await session.commit()
+        raise OidcError("This sign-in took too long. Start again.")
+    return flow
+
+
+async def complete(session: AsyncSession, code: str, flow: OidcFlow) -> dict[str, Any]:
+    return await _claims(code, flow)
+
+
+async def issue_handover(session: AsyncSession, flow: OidcFlow, user_id: int) -> str:
+    """A one-time code the page trades for a session token.
+
+    Redirecting with the session token in the URL would put it in browser history and
+    in every proxy log on the way. This is single-use and lives about a minute.
+    """
+    flow.handover = secrets.token_urlsafe(32)
+    flow.user_id = user_id
+    flow.created_at = datetime.now(UTC)
+    await session.commit()
+    return flow.handover
+
+
+async def redeem_handover(session: AsyncSession, handover: str) -> int:
+    """The user behind a handover code, which is destroyed in the process."""
+    flow = (
+        await session.execute(select(OidcFlow).where(OidcFlow.handover == handover))
+    ).scalar_one_or_none()
+    if flow is None or flow.user_id is None:
+        raise OidcError("This sign-in code is not valid")
+    expired = datetime.now(UTC) - flow.created_at.replace(tzinfo=UTC) > CODE_TTL
+    user_id = flow.user_id
+    await session.delete(flow)
+    await session.commit()
+    if expired:
+        raise OidcError("This sign-in code has expired. Start again.")
+    return user_id