gotify · jmattheis · Mar 22, 2026
diff --git a/.vitepress/config.ts b/.vitepress/config.ts
@@ -28,6 +28,7 @@ export default defineConfig({
             {text: 'Intro', link: '/docs/'},
             {text: 'Installation', link: '/docs/install'},
             {text: 'Configuration', link: '/docs/config'},
+            {text: 'OpenID Connect (OIDC)', link: '/docs/oidc'},
             {text: 'First Login', link: '/docs/first-login'},
             {text: 'Push messages', link: '/docs/pushmsg'},
             {text: 'Message Extras', link: '/docs/msgextras'},

diff --git a/docs/config.md b/docs/config.md
@@ -40,33 +40,46 @@ server:
       enabled: false # if the certificate should be requested from letsencrypt
       accepttos: false # if you accept the tos from letsencrypt
       cache: data/certs # the directory of the cache from letsencrypt
+      directoryurl: # override the directory url of the ACME server
+        # Let's Encrypt highly recommend testing against their staging environment before using their production environment.
+        # Staging server has high rate limits for testing and debugging, issued certificates are not valid
+        # example: https://acme-staging-v02.api.letsencrypt.org/directory
       hosts: # the hosts for which letsencrypt should request certificates
-  #     - mydomain.tld
-  #     - myotherdomain.tld
+  #       - mydomain.tld
+  #       - myotherdomain.tld
   responseheaders: # response headers are added to every response (default: none)
-  # X-Custom-Header: "custom value"
+  #   X-Custom-Header: "custom value"
+
   trustedproxies: # IPs or IP ranges of trusted proxies. Used to obtain the remote ip via the X-Forwarded-For header. (configure 127.0.0.1 to trust sockets)
-  #   - 127.0.0.1
-  #   - 192.168.178.0/24
+  #   - 127.0.0.1/32
   #   - ::1
+  securecookie: false # If the secure flag should be set on cookies. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#secure
 
   cors: # Sets cors headers only when needed and provides support for multiple allowed origins. Overrides Access-Control-* Headers in response headers.
     alloworigins:
-    # - ".+.example.com"
-    # - "otherdomain.com"
+    #     - ".+.example.com"
+    #     - "otherdomain.com"
     allowmethods:
-    # - "GET"
-    # - "POST"
+    #     - "GET"
+    #     - "POST"
     allowheaders:
-  #   - "Authorization"
-  #   - "content-type"
-
+  #     - "Authorization"
+  #     - "content-type"
   stream:
     pingperiodseconds: 45 # the interval in which websocket pings will be sent. Only change this value if you know what you are doing.
-    allowedorigins: # allowed origins for websocket connections (same origin is always allowed, default only same origin)
+    allowedorigins: # allowed origins for websocket connections (same origin is always allowed)
 #     - ".+.example.com"
 #     - "otherdomain.com"
-database: # see below
+oidc:
+  enabled: false # Enable OpenID Connect login, allowing users to authenticate via an external identity provider (e.g. Keycloak, Authelia, Google).
+  issuer: # The OIDC issuer URL. This is the base URL of your identity provider, used to discover endpoints. Example: "https://auth.example.com/realms/myrealm"
+  clientid: # The client ID registered with your identity provider for this application.
+  clientsecret: # The client secret for the registered client.
+  redirecturl: http://gotify.example.org/auth/oidc/callback # The callback URL that the identity provider redirects to after authentication. Must match exactly what is configured in your identity provider.
+  autoregister: true # If true, automatically create a new user on first OIDC login. If false, only existing users can log in via OIDC.
+  usernameclaim: preferred_username # The OIDC claim used to determine the username. Common values: "preferred_username" or "email".
+
+database: # for database see (configure database section)
   dialect: sqlite3
   connection: data/gotify.db
 defaultuser: # on database creation, gotify creates an admin user (these values will only be used for the first start, if you want to edit the user after the first start use the WebUI)
@@ -118,7 +131,8 @@ GOTIFY_SERVER_SSL_CERTFILE=
 GOTIFY_SERVER_SSL_CERTKEY=
 GOTIFY_SERVER_SSL_LETSENCRYPT_ENABLED=false
 GOTIFY_SERVER_SSL_LETSENCRYPT_ACCEPTTOS=false
-GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=certs
+GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=data/certs
+GOTIFY_SERVER_SSL_LETSENCRYPT_DIRECTORYURL=
 # GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS=[mydomain.tld, myotherdomain.tld]
 # GOTIFY_SERVER_RESPONSEHEADERS={X-Custom-Header: "custom value", x-other: value}
 # GOTIFY_SERVER_TRUSTEDPROXIES=[127.0.0.1,192.168.178.2/24]
@@ -127,6 +141,7 @@ GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=certs
 # GOTIFY_SERVER_CORS_ALLOWHEADERS=[X-Gotify-Key, Authorization]
 # GOTIFY_SERVER_STREAM_ALLOWEDORIGINS=[.+.example\.com, otherdomain\.com]
 GOTIFY_SERVER_STREAM_PINGPERIODSECONDS=45
+GOTIFY_SERVER_SECURECOOKIE=false
 GOTIFY_DATABASE_DIALECT=sqlite3
 GOTIFY_DATABASE_CONNECTION=data/gotify.db
 GOTIFY_DEFAULTUSER_NAME=admin
@@ -135,4 +150,11 @@ GOTIFY_PASSSTRENGTH=10
 GOTIFY_UPLOADEDIMAGESDIR=data/images
 GOTIFY_PLUGINSDIR=data/plugins
 GOTIFY_REGISTRATION=false
+GOTIFY_OIDC_ENABLED=false
+GOTIFY_OIDC_ISSUER=
+GOTIFY_OIDC_CLIENTID=
+GOTIFY_OIDC_CLIENTSECRET=
+GOTIFY_OIDC_REDIRECTURL=http://gotify.example.org/auth/oidc/callback
+GOTIFY_OIDC_AUTOREGISTER=true
+GOTIFY_OIDC_USERNAMECLAIM=preferred_username
 ```
diff --git a/docs/oidc.md b/docs/oidc.md
@@ -0,0 +1,115 @@
+# OpenID Connect (OIDC)
+
+[[toc]]
+
+Gotify supports OpenID Connect for Single Sign-On (SSO), allowing users to authenticate via an external identity provider such as Authelia or Dex.
+
+::: warning
+The identity provider **must** support [PKCE](https://oauth.net/2/pkce/) (Proof Key for Code Exchange). IdPs without PKCE support are currently unsupported.
+:::
+
+## Configuration
+
+| Key             | Description                                                                                                |
+| :-------------- | :--------------------------------------------------------------------------------------------------------- |
+| `enabled`       | Enable OIDC login.                                                                                         |
+| `issuer`        | The OIDC issuer URL. Used to discover endpoints via `/.well-known/openid-configuration`.                   |
+| `clientid`      | The client ID registered with your identity provider.                                                      |
+| `clientsecret`  | The client secret.                                                                                         |
+| `redirecturl`   | The callback URL the identity provider redirects to after authentication. Must match your provider config. |
+| `autoregister`  | Automatically create a new Gotify user on first OIDC login.                                                |
+| `usernameclaim` | The OIDC claim used to determine the username. Common values: `preferred_username` or `email`.             |
+
+::: details Gotify configuration (config.yml)
+
+```yml
+oidc:
+  enabled: true
+  issuer: https://auth.example.org
+  clientid: gotify
+  clientsecret: YOUR_CLIENT_SECRET
+  redirecturl: https://gotify.example.org/auth/oidc/callback
+  autoregister: true
+  usernameclaim: preferred_username
+```
+
+:::
+
+::: details Gotify configuration via environment variables
+
+```bash
+GOTIFY_OIDC_ENABLED=true
+GOTIFY_OIDC_ISSUER=https://auth.example.org
+GOTIFY_OIDC_CLIENTID=gotify
+GOTIFY_OIDC_CLIENTSECRET=YOUR_CLIENT_SECRET
+GOTIFY_OIDC_REDIRECTURL=https://gotify.example.org/auth/oidc/callback
+GOTIFY_OIDC_AUTOREGISTER=true
+GOTIFY_OIDC_USERNAMECLAIM=preferred_username
+```
+
+:::
+
+See the [Configuration](/docs/config) page for the full config reference.
+
+### Redirect URL
+
+- The redirect URL must always end with `/auth/oidc/callback`.
+- If Gotify is served at the root, the redirect URL is `https://gotify.example.org/auth/oidc/callback`.
+- If Gotify is served on a sub-path (e.g. behind a reverse proxy at `/gotify/`), the sub-path must be included: `https://example.org/gotify/auth/oidc/callback`.
+- For the **Android app** to support OIDC login, you must add `gotify://oidc/callback` as an additional redirect URL in your identity provider's client configuration.
+
+This URL must match **exactly** between the Gotify config and your identity provider's client configuration.
+
+## Authelia
+
+[Authelia](https://www.authelia.com/) is a self-hosted authentication and authorization server.
+
+::: details Authelia configuration (configuration.yml)
+
+```yml
+identity_providers:
+  oidc:
+    clients:
+      - client_id: 'gotify'
+        client_name: 'gotify'
+        client_secret: '$pbkdf2-sha512$310000$...' # generate with: authelia crypto hash generate pbkdf2
+        public: false
+        authorization_policy: 'two_factor'
+        require_pkce: true
+        pkce_challenge_method: 'S256'
+        consent_mode: implicit
+        redirect_uris:
+          - 'https://gotify.example.org/auth/oidc/callback' # See redirect url docs
+          - 'gotify://oidc/callback' # Required for Android app OIDC login
+        scopes:
+          - 'openid'
+          - 'profile'
+          - 'email'
+        response_types:
+          - 'code'
+        grant_types:
+          - 'authorization_code'
+        access_token_signed_response_alg: 'none'
+        userinfo_signed_response_alg: 'none'
+        token_endpoint_auth_method: 'client_secret_basic'
+```
+
+:::
+
+## Dex
+
+[Dex](https://dexidp.io/) is a federated OpenID Connect provider.
+
+::: details Dex configuration
+
+```yml
+staticClients:
+  - id: gotify
+    redirectURIs:
+      - 'https://gotify.example.org/auth/oidc/callback' # See redirect url docs
+      - 'gotify://oidc/callback' # Required for Android app OIDC login
+    name: 'Gotify'
+    secret: secret
+```
+
+:::