OpenID Connect (OIDC)

Set QUI__OIDC_ENABLED=true to delegate authentication to an external identity provider. You must also set the issuer, client ID, client secret, and redirect URL. If one of these values is missing, or qui cannot reach the issuer, qui does not start. When OIDC is enabled, the login screen shows an OpenID Connect button.

If your provider advertises PKCE (S256) support, qui uses it for the authorization flow. You do not need to configure extra settings in qui. To make sure that PKCE is active, inspect /api/auth/oidc/config. The authorizationUrl must include both code_challenge= and code_challenge_method=S256. qui does not emit a dedicated "PKCE enabled" log line, so check the authorization URL directly.

qui accepts every identity that the provider permits for the qui client. qui has one user and no identity allowlist of its own. Restrict the client on the provider side, for example with a group or user assignment, so that only you can sign in.

An https:// redirect URL marks the session cookie as Secure, so the browser sends it only over HTTPS. See Sessions.

For the full mapping (TOML keys + environment variables + defaults), see Configuration Reference.

Configuration options

Variable	Description
QUI__OIDC_ISSUER	Issuer URL from your IdP (for example https://auth.example.com/realms/main)
QUI__OIDC_CLIENT_ID	Client ID registered for qui
QUI__OIDC_CLIENT_SECRET	Client secret generated by the provider
QUI__OIDC_CLIENT_SECRET_FILE	Path to a file that contains the client secret. This setting overrides QUI__OIDC_CLIENT_SECRET
QUI__OIDC_REDIRECT_URL	Must match the redirect URI allowed by the provider
QUI__OIDC_DISABLE_BUILT_IN_LOGIN	When OIDC is enabled, set to true to hide the local username/password form

Redirect URL format

If you use a default install, use:

http://localhost:7476/api/auth/oidc/callback

If you use a reverse proxy, include your base URL:

https://host/qui/api/auth/oidc/callback

If you run OIDC behind an SSO proxy (for example Cloudflare Access or Pangolin), read SSO proxies and CORS for browser fetch behavior and proxy-side configuration.

Example configuration

QUI__OIDC_ENABLED=true \
QUI__OIDC_ISSUER=https://auth.example.com/realms/main \
QUI__OIDC_CLIENT_ID=qui \
QUI__OIDC_CLIENT_SECRET=super-secret-value \
QUI__OIDC_REDIRECT_URL=https://qui.example.com/api/auth/oidc/callback \
QUI__OIDC_DISABLE_BUILT_IN_LOGIN=true \
qui serve

You can set the same options in config.toml with the oidc* keys that qui generate-config writes.