From 1dc281692e7856f1d9f4e69f3b64da0d0ee76a80 Mon Sep 17 00:00:00 2001 From: Jannis Mattheis Date: Wed, 26 Aug 2026 19:37:59 +0200 Subject: [PATCH 1/2] fix: add new oidc settings --- docs/oidc.md | 61 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 50 insertions(+), 11 deletions(-) diff --git a/docs/oidc.md b/docs/oidc.md index 3b1231d..1f0f30c 100644 --- a/docs/oidc.md +++ b/docs/oidc.md @@ -10,17 +10,23 @@ The identity provider **must** support [PKCE](https://oauth.net/2/pkce/) (Proof ## Configuration -| Variable | Description | -| :----------------------------- | :--------------------------------------------------------------------------------------------------------- | -| `GOTIFY_OIDC_ENABLED` | Enable OIDC login. | -| `GOTIFY_OIDC_ISSUER` | The OIDC issuer URL. Used to discover endpoints via `/.well-known/openid-configuration`. | -| `GOTIFY_OIDC_CLIENTID` | The client ID registered with your identity provider. | -| `GOTIFY_OIDC_CLIENTSECRET` | The client secret. | -| `GOTIFY_OIDC_REDIRECTURL` | The callback URL the identity provider redirects to after authentication. Must match your provider config. | -| `GOTIFY_OIDC_AUTOREGISTER` | Automatically create a new Gotify user on first OIDC login. Enabled by default. | -| `GOTIFY_OIDC_USERNAMECLAIM` | The OIDC claim used as the username. Common values: `preferred_username` (default) or `email`. | -| `GOTIFY_OIDC_LINK_BY_USERNAME` | Link an OIDC identity to an existing local user with the same username. Disabled by default. | -| `GOTIFY_OIDC_SCOPES` | Comma-separated scopes to request. Defaults to `openid,profile,email`. | +| Variable | Description | +| :----------------------------- | :----------------------------------------------------------------------------------------------------------- | +| `GOTIFY_OIDC_ENABLED` | Enable OIDC login. | +| `GOTIFY_OIDC_ISSUER` | The OIDC issuer URL. Used to discover endpoints via `/.well-known/openid-configuration`. | +| `GOTIFY_OIDC_CLIENTID` | The client ID registered with your identity provider. | +| `GOTIFY_OIDC_CLIENTSECRET` | The client secret. | +| `GOTIFY_OIDC_REDIRECTURL` | The callback URL the identity provider redirects to after authentication. Must match your provider config. | +| `GOTIFY_OIDC_AUTOREGISTER` | Automatically create a new Gotify user on first OIDC login. Enabled by default. | +| `GOTIFY_OIDC_USERNAMECLAIM` | The OIDC claim used as the username. Common values: `preferred_username` (default) or `email`. | +| `GOTIFY_OIDC_LINK_BY_USERNAME` | Link an OIDC identity to an existing local user with the same username. Disabled by default. | +| `GOTIFY_OIDC_SCOPES` | Comma-separated scopes to request. Defaults to `openid,profile,email`. | +| `GOTIFY_OIDC_PROMPT` | Comma-separated values for the `prompt` authorization parameter. Defaults to `login`. | +| `GOTIFY_OIDC_IDP_NAME` | Name of the identity provider displayed in the UI. Defaults to `OIDC`. | +| `GOTIFY_OIDC_AUTO_REDIRECT` | Automatically redirect to the identity provider instead of showing the login page. Disabled by default. | +| `GOTIFY_OIDC_GROUPS_CLAIM` | The claim containing the user's group memberships. Empty (default) disables [group mapping](#groups). | +| `GOTIFY_OIDC_GROUPS_USER` | Comma-separated groups whose members may log in with user permissions. Empty allows all authenticated users. | +| `GOTIFY_OIDC_GROUPS_ADMIN` | Comma-separated groups whose members are granted admin permissions. | ```bash GOTIFY_OIDC_ENABLED=true @@ -32,6 +38,12 @@ GOTIFY_OIDC_AUTOREGISTER=true GOTIFY_OIDC_USERNAMECLAIM=preferred_username GOTIFY_OIDC_LINK_BY_USERNAME=false GOTIFY_OIDC_SCOPES=openid,profile,email +GOTIFY_OIDC_PROMPT=login +GOTIFY_OIDC_IDP_NAME=OIDC +GOTIFY_OIDC_AUTO_REDIRECT=false +GOTIFY_OIDC_GROUPS_CLAIM= +GOTIFY_OIDC_GROUPS_USER= +GOTIFY_OIDC_GROUPS_ADMIN= ``` See the [Configuration](/docs/config) page for the full config reference. @@ -51,6 +63,25 @@ Gotify identifies users by username. By default, an OIDC login is rejected when Only enable this if you trust that usernames in your identity provider map to the same people as your Gotify usernames. +## Groups + +Set `GOTIFY_OIDC_GROUPS_CLAIM` to manage Gotify permissions via the group memberships from your identity provider. The claim must contain the groups as a list of strings and must be included in the requested scopes. Most identity providers expose it via the `groups` scope. + +```bash +GOTIFY_OIDC_SCOPES=openid,profile,email,groups +GOTIFY_OIDC_GROUPS_CLAIM=groups +GOTIFY_OIDC_GROUPS_USER=gotify-users +GOTIFY_OIDC_GROUPS_ADMIN=gotify-admins +``` + +With this configuration: + +- Members of `gotify-admins` log in with admin permissions. +- Members of `gotify-users` log in with user permissions. +- Everyone else is denied access. + +When `GOTIFY_OIDC_GROUPS_ADMIN` is set, the admin permission is updated on every login, overwriting manual changes done in Gotify. + ## Sample IdP configurations ### Authelia @@ -78,6 +109,7 @@ identity_providers: - 'openid' - 'profile' - 'email' + - 'groups' # Required for group mapping response_types: - 'code' grant_types: @@ -87,6 +119,8 @@ identity_providers: token_endpoint_auth_method: 'client_secret_basic' ``` +For [group mapping](#groups): Authelia exposes the user's groups via the `groups` scope and claim, see the [Authelia claims docs](https://www.authelia.com/integration/openid-connect/openid-connect-1.0-claims/#groups). + ::: ### Authentik @@ -95,6 +129,8 @@ identity_providers: See https://integrations.goauthentik.io/monitoring/gotify/ +For [group mapping](#groups): authentik exposes the user's groups via the `groups` claim inside the default `profile` scope, see the [authentik scope mapping docs](https://docs.goauthentik.io/add-secure-apps/providers/oauth2/#default-scopes). + ### Dex [Dex](https://dexidp.io/) is a federated OpenID Connect provider. @@ -111,6 +147,8 @@ staticClients: secret: secret ``` +For [group mapping](#groups): Dex exposes the user's groups via the `groups` scope and claim, see the [Dex scopes and claims docs](https://dexidp.io/docs/configuration/custom-scopes-claims-clients/). The available groups depend on the configured connector. + ::: ### Pocket ID @@ -127,6 +165,7 @@ staticClients: ``` 1. Enable PKCE. 1. Optional: Download a PNG or SVG logo from the Gotify project and upload. +1. Optional for [group mapping](#groups): Pocket ID exposes the user groups via the `groups` scope and claim. See https://github.com/pocket-id/pocket-id/discussions/275. 1. Copy the Client ID and Client Secret for use in the next section. ::: From 70f242edb55dc0024f6e6aaed2a0ed2db13fe51a Mon Sep 17 00:00:00 2001 From: Jannis Mattheis Date: Wed, 26 Aug 2026 19:43:10 +0200 Subject: [PATCH 2/2] fix: document disable localauth --- docs/oidc.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/oidc.md b/docs/oidc.md index 1f0f30c..19bbe7a 100644 --- a/docs/oidc.md +++ b/docs/oidc.md @@ -82,6 +82,16 @@ With this configuration: When `GOTIFY_OIDC_GROUPS_ADMIN` is set, the admin permission is updated on every login, overwriting manual changes done in Gotify. +## Disabling local authentication + +When all users log in via OIDC, local username/password authentication can be disabled: + +```bash +GOTIFY_LOCALAUTH_ENABLED=false +``` + +This hides the password login form in the WebUI and rejects username/password authentication (including basic auth) on the API. + ## Sample IdP configurations ### Authelia