Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

docs/02-security/CHATGPT_OAUTH_CONNECTION_PERSISTENCE.md

@@ -0,0 +1,55 @@
+# ChatGPT OAuth connection persistence
+
+The public MCP endpoint is expected to remain connected in ChatGPT without periodic interactive re-authorization while the OAuth grant remains valid.
+
+## Required provider contract
+
+The Authentik OAuth2/OIDC provider used by the ChatGPT MCP app must expose the `offline_access` scope mapping in addition to `openid`, `profile`, and `email`. This lets a compliant OAuth client request a refresh token instead of depending only on the original access token.
+
+Production configuration therefore requires:
+
+```text
+AUTHENTIK_SCOPES=openid,profile,email,groups,offline_access
+```
+
+`groups` remains required by the Hub's existing role mapping. The ChatGPT
+provider itself uses `openid profile email offline_access`. The public
+protected-resource metadata and the MCP `401 WWW-Authenticate` challenge must
+advertise that same refresh-capable scope set. `promotion_preflight.py` fails
+closed when either `openid` or `offline_access` is absent.
+
+## Authentik one-time reconciliation
+
+In the Authentik admin interface, open the OAuth2/OIDC provider backing the
+ChatGPT application (`Provider for ChatGPT - ITWorx Gitea` in production) and
+include the built-in `offline_access` scope mapping under Scope mappings. This
+is distinct from the browser-facing Hub provider. Keep the authorization-code
+flow enabled and keep refresh-token support enabled. Do not weaken redirect
+URI, PKCE, audience, or group restrictions to obtain persistence.
+
+After changing the provider, verify its OpenID discovery metadata advertises `offline_access` in `scopes_supported` and verify an authorization requesting that scope receives a refresh token.
+
+Run production preflight with `--verify-oidc-discovery`. This checks both the
+browser-facing Hub issuer and the ChatGPT issuer for an exact issuer, HTTPS
+authorization/token endpoints, authorization-code and refresh-token grants,
+S256 PKCE, and `openid` plus `offline_access` publication.
+
+## Validated production settings
+
+The production ChatGPT provider is confidential and uses one strict
+`https://chatgpt.com/connector/oauth/...` redirect. Its access tokens are valid
+for five minutes. Refresh tokens are valid for 365 days and the refresh
+threshold is `seconds=0`; on the deployed Authentik version this rotates the
+refresh token on every successful refresh and revokes the prior token. These
+settings preserve short access-token exposure, revocability, and durable
+connections without disabling PKCE or widening redirect matching.
+
+## ChatGPT reconciliation
+
+OAuth metadata can be cached at app creation time. After the provider is corrected, recreate or reconnect the ChatGPT MCP app once so ChatGPT reads the updated provider metadata. Thereafter access-token renewal should use the refresh token and should not require routine interactive reconnects.
+
+A future reconnect can still be legitimate after explicit revocation, refresh-token expiry or rotation failure, provider/client reconfiguration, security-policy changes, or deletion/recreation of the ChatGPT app.
+
+## Operational rule
+
+Do not work around reconnect prompts by making access tokens effectively permanent or by replacing user OAuth with a shared long-lived bearer token. Refresh-token based OAuth persistence preserves revocability and the existing identity boundary.