feat: generic OIDC/XOAUTH2 support for individual mail accounts#13317
Open
LeahAuroraV wants to merge 8 commits into
Open
feat: generic OIDC/XOAUTH2 support for individual mail accounts#13317LeahAuroraV wants to merge 8 commits into
LeahAuroraV wants to merge 8 commits into
Conversation
Let an administrator register OpenID Connect providers so users whose email domain matches can authenticate their IMAP/SMTP connection over XOAUTH2 via an interactive authorization-code flow, instead of storing a password. This generalises the existing Google and Microsoft integrations to any OIDC provider (Keycloak, Authentik, Stalwart, ...). - New `mail_oidc_providers` table with `OidcProvider` entity and mapper (matched to accounts by the user's email domain; separate IMAP/SMTP host/port/SSL, client id/secret, discovery URL or manual endpoints, scopes). - `OidcIntegration` service: discovery fetch and cache (or admin-defined endpoints), authorization-code exchange, cron-safe token refresh, and provider CRUD with the client secret encrypted at rest. - `OidcIntegrationController` and routes: admin CRUD, the authorize redirect that resolves discovery server-side, and the OAuth callback, reusing `OauthStateService`. - `OauthTokenRefreshListener`: refresh the OIDC token before IMAP connect, mirroring the Google/Microsoft branches. - Admin UI (`OidcAdminSettings` / `OidcProviderForm`) to manage 0..n providers and `AccountForm` email-domain detection that pre-fills the mail servers and opens the SSO consent popup. - Documentation and unit tests. Two deliberate divergences from the reviewer's earlier sketch, to be flagged on the PR: multiple providers (0..n) rather than a single global config, and matching by email domain rather than IMAP hostname. Closes nextcloud#12491 Assisted-by: Claude:claude-opus-4-8 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Leah <leahvenema@hotmail.com>
LeahAuroraV
requested review from
ChristophWurst,
GretaD and
kesselb
as code owners
July 18, 2026 22:23
|
Thanks for opening your first pull request in this repository! ✌️ |
LeahAuroraV
marked this pull request as draft
July 19, 2026 23:08
Author
|
Adding some functionality to handle expired, revoked or non-existent refresh tokens first before this is ready for review |
…enewed A refresh token eventually expires or is revoked, for example after an extended outage where nothing synced, and OAuth offers no way to know that lifetime up front. Until now the refresh simply failed, background sync quietly stopped and the user was left to work out that the account needed attention. A failed refresh is no longer trusted on its own: the provider is asked through its introspection endpoint (RFC 7662) whether the refresh token is still active. Only a definitive "no", or having no refresh token at all while the access token has expired, marks the account as needing re-authentication, so a provider that is merely unreachable is still treated as a temporary problem. The flag is cleared again as soon as any refresh or reconnect succeeds. A flagged account raises a dialog when Mail is opened, which reconnects it through the same consent popup used during setup and then pulls the mailbox list that could not sync while the grant was dead. The popup is opened from the button press so it keeps the user activation browsers require. A broken OAuth account has no password to change, so the navigation error offers to reconnect instead. The introspection endpoint is read from the discovery document, or can be entered by hand next to the other endpoints for providers configured that way. Without one a rejected refresh is never treated as a dead grant. Also splits the OidcIntegration unit tests into per-behaviour classes sharing a common fixture, as the single test class had grown unwieldy. Assisted-by: Claude:claude-opus-4-8 Signed-off-by: Leah <leahvenema@hotmail.com>
Member
|
Thanks for looking into this 🙏 |
Draft
1 task
Until now the reconnect dialog only appeared when an account was already flagged for re-authentication in the initial page state. When Mail tests each account's connection on load it creates an IMAP client, which runs the token refresh on the server and may flag the account then and there, so re-read that flag afterwards to let the dialog show in the same session. Because the connection test uses a lazily-connecting client it can return success even when the grant is dead, so the flag is re-read for every OIDC account rather than only on a reported failure. Only the single flag is patched to avoid re-adding the account to the list. Assisted-by: Claude:claude-opus-4-8 Signed-off-by: Leah <leahvenema@hotmail.com>
…tions The new oauth_needs_reauth flag is exposed by MailAccount::toJson(), so the two integration tests asserting the full serialized array need it too. Assisted-by: Claude:claude-opus-4-8 Signed-off-by: Leah <leahvenema@hotmail.com>
Assisted-by: Claude:claude-opus-4-8 Signed-off-by: Leah <leahvenema@hotmail.com>
LeahAuroraV
marked this pull request as ready for review
July 20, 2026 11:49
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #12491
Individual OIDC / XOAUTH2 support
Follow-up to #13311. In the review Christoph suggested "getting individual OIDC support in first and closing #12491", and then building the provisioning on top of that. So here's generic oidc for nextcloud mail.
It's basically the same idea as the Google/Microsoft integrations that already exist, just generalised to any OIDC provider. An admin registers one or more providers in the groupware admin settings (client id + secret, a discovery url or the endpoints directly, imap/smtp servers). When a user adds a mail account whose email domain matches one of those, mail pre-fills the servers and opens the consent popup, the code gets exchanged server-side and the account authenticates over XOAUTH2 with no stored password. tokens get refreshed via the stored refresh token for background/cron sync, same as google/ms.
Testing
Developed against authentik with dovecot + postfix set up to accept XOAUTH2. Verified the whole thing locally: add account -> popup -> consent -> imap sync + smtp send, then force-expire the token and confirm background refresh still works.
There's a documentation file that described how to get a test envionment up and running in doc/oidc-xoauth2.md.
Changes
mail_oidc_providerstable +OidcProviderentity/mapper (email domain, separate imap/smtp host/port/ssl, client id/secret, discovery url or manual endpoints, scopes)OidcIntegrationservice: discovery fetch + cache (or manual endpoints), auth-code exchange, token refresh, provider CRUD (secret encrypted at rest)OidcIntegrationController+ routes: admin CRUD, the authorize redirect (resolves discovery server-side and 302s to the idp) and the oauth callback, reusingOauthStateServiceOauthTokenRefreshListener: refresh the oidc token before imap connect, next to the google/ms branchesAccountFormemail-domain detection -> pre-fill + sso popupcloses #12491
🤖 AI (if applicable)