Skip to content

Commit 0307309

Browse files
jmattheisjmattheis
committed
feat: oidc
1 parent cf61685 commit 0307309

3 files changed

Lines changed: 153 additions & 15 deletions

File tree

‎.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ export default defineConfig({
2828
{text: 'Intro', link: '/docs/'},
2929
{text: 'Installation', link: '/docs/install'},
3030
{text: 'Configuration', link: '/docs/config'},
31+
{text: 'OpenID Connect (OIDC)', link: '/docs/oidc'},
3132
{text: 'First Login', link: '/docs/first-login'},
3233
{text: 'Push messages', link: '/docs/pushmsg'},
3334
{text: 'Message Extras', link: '/docs/msgextras'},

‎docs/config.md‎

Lines changed: 37 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -40,33 +40,46 @@ server:
4040
enabled: false # if the certificate should be requested from letsencrypt
4141
accepttos: false # if you accept the tos from letsencrypt
4242
cache: data/certs # the directory of the cache from letsencrypt
43+
directoryurl: # override the directory url of the ACME server
44+
# Let's Encrypt highly recommend testing against their staging environment before using their production environment.
45+
# Staging server has high rate limits for testing and debugging, issued certificates are not valid
46+
# example: https://acme-staging-v02.api.letsencrypt.org/directory
4347
hosts: # the hosts for which letsencrypt should request certificates
44-
# - mydomain.tld
45-
# - myotherdomain.tld
48+
# - mydomain.tld
49+
# - myotherdomain.tld
4650
responseheaders: # response headers are added to every response (default: none)
47-
# X-Custom-Header: "custom value"
51+
# X-Custom-Header: "custom value"
52+
4853
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)
49-
# - 127.0.0.1
50-
# - 192.168.178.0/24
54+
# - 127.0.0.1/32
5155
# - ::1
56+
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
5257

5358
cors: # Sets cors headers only when needed and provides support for multiple allowed origins. Overrides Access-Control-* Headers in response headers.
5459
alloworigins:
55-
# - ".+.example.com"
56-
# - "otherdomain.com"
60+
# - ".+.example.com"
61+
# - "otherdomain.com"
5762
allowmethods:
58-
# - "GET"
59-
# - "POST"
63+
# - "GET"
64+
# - "POST"
6065
allowheaders:
61-
# - "Authorization"
62-
# - "content-type"
63-
66+
# - "Authorization"
67+
# - "content-type"
6468
stream:
6569
pingperiodseconds: 45 # the interval in which websocket pings will be sent. Only change this value if you know what you are doing.
66-
allowedorigins: # allowed origins for websocket connections (same origin is always allowed, default only same origin)
70+
allowedorigins: # allowed origins for websocket connections (same origin is always allowed)
6771
# - ".+.example.com"
6872
# - "otherdomain.com"
69-
database: # see below
73+
oidc:
74+
enabled: false # Enable OpenID Connect login, allowing users to authenticate via an external identity provider (e.g. Keycloak, Authelia, Google).
75+
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"
76+
clientid: # The client ID registered with your identity provider for this application.
77+
clientsecret: # The client secret for the registered client.
78+
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.
79+
autoregister: true # If true, automatically create a new user on first OIDC login. If false, only existing users can log in via OIDC.
80+
usernameclaim: preferred_username # The OIDC claim used to determine the username. Common values: "preferred_username" or "email".
81+
82+
database: # for database see (configure database section)
7083
dialect: sqlite3
7184
connection: data/gotify.db
7285
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=
118131
GOTIFY_SERVER_SSL_CERTKEY=
119132
GOTIFY_SERVER_SSL_LETSENCRYPT_ENABLED=false
120133
GOTIFY_SERVER_SSL_LETSENCRYPT_ACCEPTTOS=false
121-
GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=certs
134+
GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=data/certs
135+
GOTIFY_SERVER_SSL_LETSENCRYPT_DIRECTORYURL=
122136
# GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS=[mydomain.tld, myotherdomain.tld]
123137
# GOTIFY_SERVER_RESPONSEHEADERS={X-Custom-Header: "custom value", x-other: value}
124138
# GOTIFY_SERVER_TRUSTEDPROXIES=[127.0.0.1,192.168.178.2/24]
@@ -127,6 +141,7 @@ GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=certs
127141
# GOTIFY_SERVER_CORS_ALLOWHEADERS=[X-Gotify-Key, Authorization]
128142
# GOTIFY_SERVER_STREAM_ALLOWEDORIGINS=[.+.example\.com, otherdomain\.com]
129143
GOTIFY_SERVER_STREAM_PINGPERIODSECONDS=45
144+
GOTIFY_SERVER_SECURECOOKIE=false
130145
GOTIFY_DATABASE_DIALECT=sqlite3
131146
GOTIFY_DATABASE_CONNECTION=data/gotify.db
132147
GOTIFY_DEFAULTUSER_NAME=admin
@@ -135,4 +150,11 @@ GOTIFY_PASSSTRENGTH=10
135150
GOTIFY_UPLOADEDIMAGESDIR=data/images
136151
GOTIFY_PLUGINSDIR=data/plugins
137152
GOTIFY_REGISTRATION=false
153+
GOTIFY_OIDC_ENABLED=false
154+
GOTIFY_OIDC_ISSUER=
155+
GOTIFY_OIDC_CLIENTID=
156+
GOTIFY_OIDC_CLIENTSECRET=
157+
GOTIFY_OIDC_REDIRECTURL=http://gotify.example.org/auth/oidc/callback
158+
GOTIFY_OIDC_AUTOREGISTER=true
159+
GOTIFY_OIDC_USERNAMECLAIM=preferred_username
138160
```

‎docs/oidc.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# OpenID Connect (OIDC)
2+
3+
[[toc]]
4+
5+
Gotify supports OpenID Connect for Single Sign-On (SSO), allowing users to authenticate via an external identity provider such as Authelia or Dex.
6+
7+
::: warning
8+
The identity provider **must** support [PKCE](https://oauth.net/2/pkce/) (Proof Key for Code Exchange). IdPs without PKCE support are currently unsupported.
9+
:::
10+
11+
## Configuration
12+
13+
| Key | Description |
14+
| :-------------- | :--------------------------------------------------------------------------------------------------------- |
15+
| `enabled` | Enable OIDC login. |
16+
| `issuer` | The OIDC issuer URL. Used to discover endpoints via `/.well-known/openid-configuration`. |
17+
| `clientid` | The client ID registered with your identity provider. |
18+
| `clientsecret` | The client secret. May be omitted if using a public client with PKCE. |
19+
| `redirecturl` | The callback URL the identity provider redirects to after authentication. Must match your provider config. |
20+
| `autoregister` | Automatically create a new Gotify user on first OIDC login. |
21+
| `usernameclaim` | The OIDC claim used to determine the username. Common values: `preferred_username` or `email`. |
22+
23+
::: details Gotify configuration (config.yml)
24+
25+
```yml
26+
oidc:
27+
enabled: true
28+
issuer: https://auth.example.org
29+
clientid: gotify
30+
clientsecret: YOUR_CLIENT_SECRET
31+
redirecturl: https://gotify.example.org/auth/oidc/callback
32+
autoregister: true
33+
usernameclaim: preferred_username
34+
```
35+
36+
:::
37+
38+
::: details Gotify configuration via environment variables
39+
40+
```bash
41+
GOTIFY_OIDC_ENABLED=true
42+
GOTIFY_OIDC_ISSUER=https://auth.example.org
43+
GOTIFY_OIDC_CLIENTID=gotify
44+
GOTIFY_OIDC_CLIENTSECRET=YOUR_CLIENT_SECRET
45+
GOTIFY_OIDC_REDIRECTURL=https://gotify.example.org/auth/oidc/callback
46+
GOTIFY_OIDC_AUTOREGISTER=true
47+
GOTIFY_OIDC_USERNAMECLAIM=preferred_username
48+
```
49+
50+
:::
51+
52+
See the [Configuration](/docs/config) page for the full config reference.
53+
54+
### Redirect URL
55+
56+
- The redirect URL must always end with `/auth/oidc/callback`.
57+
- If Gotify is served at the root, the redirect URL is `https://gotify.example.org/auth/oidc/callback`.
58+
- 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`.
59+
- 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.
60+
61+
This URL must match **exactly** between the Gotify config and your identity provider's client configuration.
62+
63+
## Authelia
64+
65+
[Authelia](https://www.authelia.com/) is a self-hosted authentication and authorization server.
66+
67+
::: details Authelia configuration (configuration.yml)
68+
69+
```yml
70+
identity_providers:
71+
oidc:
72+
clients:
73+
- client_id: 'gotify'
74+
client_name: 'gotify'
75+
client_secret: '$pbkdf2-sha512$310000$...' # generate with: authelia crypto hash generate pbkdf2
76+
public: false
77+
authorization_policy: 'two_factor'
78+
require_pkce: true
79+
pkce_challenge_method: 'S256'
80+
consent_mode: implicit
81+
redirect_uris:
82+
- 'https://gotify.example.org/auth/oidc/callback' # See redirect url docs
83+
- 'gotify://oidc/callback' # Required for Android app OIDC login
84+
scopes:
85+
- 'openid'
86+
- 'profile'
87+
- 'email'
88+
response_types:
89+
- 'code'
90+
grant_types:
91+
- 'authorization_code'
92+
access_token_signed_response_alg: 'none'
93+
userinfo_signed_response_alg: 'none'
94+
token_endpoint_auth_method: 'client_secret_basic'
95+
```
96+
97+
:::
98+
99+
## Dex
100+
101+
[Dex](https://dexidp.io/) is a federated OpenID Connect provider.
102+
103+
::: details Dex configuration
104+
105+
```yml
106+
staticClients:
107+
- id: gotify
108+
redirectURIs:
109+
- 'https://gotify.example.org/auth/oidc/callback' # See redirect url docs
110+
- 'gotify://oidc/callback' # Required for Android app OIDC login
111+
name: 'Gotify'
112+
secret: secret
113+
```
114+
115+
:::

0 commit comments

Comments
 (0)