Skip to content

OIDC Server#941

Open
jmattheis wants to merge 13 commits intomasterfrom
oidc
Open

OIDC Server#941
jmattheis wants to merge 13 commits intomasterfrom
oidc

Conversation

@jmattheis
Copy link
Copy Markdown
Member

This MR:

  • Refactors the auth handling by replacing the old requireToken / callback structure with a simpler approach.
  • Adds cookie-based token reading and /auth/local/{login,logout} endpoints for web UI authentication.
    • Without this, we'd have to redirect to an url https://gotify-ui.net/#/oidc/callback?token=... to store the token in the local storage. Using cookies seems to be more easy than securing this against CSRF and stuff. Also with HttpOnly cookies we guard against pontential token exposures.
    • Secure cookies are supported but disabled by default to avoid breaking existing HTTP installations. We could detect HTTPS via the Referer or X-Forwarded-Proto headers in the future.
  • Add /gotifyinfo endpoint. In the android app we need to know if oidc is enabled, and the android app also displays the version. I didn't want to add this information to the /version endpoint so it's a new endpoint. I don't really like the naming, but I wanted something unique so that the android app can be sure it's a gotify/server instance.

Web UI: Standard OAuth2 Authorization Code + PKCE

This is the standard OIDC implementation with a library.

  • A "Login with OIDC" button appears when OIDC is enabled (This is only visible in the production build, when the UI is served by gotify/server)
  • Clicking it redirects to GET /auth/oidc/login, which then redirects to the IdP.
  • After authentication the IdP redirects to /auth/oidc/callback, which:
    1. Exchanges the authorization code for tokens.
    2. Resolves the user via the userinfo endpoint (creating the user if configured).
    3. Creates a Gotify client, sets the session cookie, and redirects to the UI.

Android App flow

Android's recommended App Links (verified domains) aren't usable here because the server is self-hosted at a user-chosen domain.

I guess most of the android app, are doing their own OIDC flow against the IdP server to then obtain a token from the IdP server to then access the resources with the token. In our case, we need a client token from gotify.

We could let the android app do the whole OIDC flow, but this would require us to have a public oauth2 client, as we don't want to store the client_secret in the android app. Requesting the client secret from the server seems like a bad idea.

Another simple implementation would be to do the same flow as the Web-UI, but in the end redirecting to a custom URI scheme like gotify://oidc/callback?token=C123123123 and then using this token for authentication. I've decided against this because the custom URI scheme can be set by any app, and therefore intercept the token.

PKCE was exactly made to prevent this, so I've searched for a way to still get the benefits from PKCE, but not having to reimplement a OIDC like handshake.

This flow is non standard but it's basically stolen from Vaultwarden. I'm not that deep in security, but I'd expect they spend some time designing this, and ensuring it's secure.

It works like this.

  1. The app generates a PKCE code_verifier / code_challenge pair.
  2. The app POST /auth/oidc/external/authorize with code_challenge, a custom-scheme redirect_uri, and a client name. The server stores a pending session keyed by a random state token, and then reponds with the the authorization URL + state. Vaultwarden 1, Vaultwarden 2,
  3. The app opens the authorization URL in a browser. The IdP authenticates the user and redirects to the app's custom URI (gotify://oidc/callback) with code and state.
  4. POST /auth/oidc/external/token with code, state, and code_verifier. The server gets the pending session, relays the code_verifier to the IdP for PKCE validation, exchanges the code for tokens, resolves the user, and returns a Gotify client token + user info. Vaultwarden 1, Vaultwarden 2

PKCE is required, and only verified by the IdP. We could support non PKCE IdP by manually validating the challange on the /auth/oidc/external/token endpoint, simliar to Vaultwarden Impl, but I think most of the Idp will support PKCE, so it's required until someone requests it.

For testing I've added Dex and Authelia config in ./test/oidc.

Related MRs:

I've manually tested this with:

  • Web-UI: Dex (on root, and subpath /gotify/ with a reverse proxy) and authelia
  • Android with Dex and Authelia

Disclaimer: this PR was created with AI assistance.

Add two new endpoints for native app OIDC authentication using the
PKCE relay pattern (similar to Vaultwarden's SSO implementation):

- POST /auth/oidc/external/authorize - accepts a PKCE code_challenge
from the client, forwards it to the IdP, and returns the authorize URL
- POST /auth/oidc/external/token - accepts the auth code and
code_verifier, relays them to the IdP for token exchange, and returns
a gotify client token

The server never generates its own PKCE pair for this flow. It then relays
the client's code_challenge to the IdP during authorization and the
code_verifier during token exchange. The IdP validates the binding.
Pending auth sessions are stored in memory with a 10-minute TTL.

CSRF protection is provided by the state parameter, which contains a
cryptographically random nonce and is validated on the token exchange.
The state is single-use (deleted from the pending session map on lookup),
preventing replay attacks. Even without single-use enforcement, replay
would be harmless since the IdP's authorization code can only be
exchanged once.
It's not easy to test this automatically without a real oidc server.
@jmattheis jmattheis requested a review from a team as a code owner March 29, 2026 21:19
@codecov
Copy link
Copy Markdown

codecov bot commented Mar 29, 2026

Codecov Report

❌ Patch coverage is 53.82353% with 157 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.92%. Comparing base (0610537) to head (c463d98).
⚠️ Report is 1 commits behind head on master.

Files with missing lines Patch % Lines
api/oidc.go 33.11% 99 Missing and 4 partials ⚠️
auth/authentication.go 77.88% 11 Missing and 12 partials ⚠️
api/session.go 55.31% 13 Missing and 8 partials ⚠️
router/router.go 52.38% 8 Missing and 2 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #941      +/-   ##
==========================================
- Coverage   78.70%   75.92%   -2.79%     
==========================================
  Files          57       60       +3     
  Lines        2517     2758     +241     
==========================================
+ Hits         1981     2094     +113     
- Misses        397      514     +117     
- Partials      139      150      +11     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@@ -16,7 +16,7 @@ type HealthAPI struct {
}
Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eternal-flame-AD sorry this is kinda big, but would you mind having a look at this? Don't worry about declining if you don't want to review this, or don't have the time. I don't want to burden you with this :D.

Anyway, my plan is to create a snapshot docker build in the coming days and then let the people in #433 try out the functionality to improve the user-guide and find possible bugs with special IdP servers. So there is no rush reviewing this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant