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.
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.