Skip to content

feat(mail): document generic OIDC/XOAUTH2 integration #16017

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ChristophWurst wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(mail): document generic OIDC/XOAUTH2 integration #16017

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions admin_manual/groupware/mail.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,52 @@ Congratulations! You are now able to use hosted Microsoft Outlook accounts in th

.. figure:: images/azure_xoauth2/10.png

Generic OpenID Connect (XOAUTH2) integration
--------------------------------------------

.. versionadded:: 6.0

In addition to the built-in Google and Microsoft integrations, the Mail app can authenticate
individual mail accounts over XOAUTH2 against any OpenID Connect provider, for example
Keycloak, Authentik or Stalwart. An administrator registers one or more providers, each
matched to accounts by the user's email domain.

**Step 1: Register an OAuth client with your identity provider**

Create a confidential (web) OAuth client with your identity provider and authorize the
redirect URL shown in the provider form, ``https://<your-nextcloud>/index.php/apps/mail/integration/oidc-auth``.
Grant it the scopes needed to issue mail and refresh tokens (``openid email offline_access``
by default), and make sure the access tokens it issues are accepted by your IMAP/SMTP server
for XOAUTH2.
Comment on lines +206 to +207

@Leah-BW Leah-BW Nov 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Mail logs in with the full email address as the IMAP and SMTP username (AccountForm::applyOidcProvider() sets imapUser/smtpUser to it), so the mail server has to map the token to that login. Otherwise XOAUTH2 fails even with a valid token.

Suggested change
by default), and make sure the access tokens it issues are accepted by your IMAP/SMTP server
for XOAUTH2.
by default), and make sure the access tokens it issues are accepted by your IMAP/SMTP server
for XOAUTH2. Mail uses the full email address as the IMAP and SMTP username, so the server
must map the token to that login (for example via Dovecot's ``username_attribute``).


**Step 2: Configure the provider in Nextcloud**

Open the groupware admin settings and find *OpenID Connect integration*. Click *Add OIDC
provider* and fill in:

- **Display name** -- a free-text label.
- **Email domain** -- accounts whose address is in this domain use this provider.
- **IMAP** and **SMTP** -- host, port and encryption for the mail servers. The two may differ.
- **Discovery endpoint** -- the provider's ``.well-known/openid-configuration`` URL.
Providers that don't publish one can instead have their authorization, token and
(optional) introspection endpoints entered manually.
- **Client ID** / **Client secret** -- the credentials of the OAuth client from step 1. The
secret is stored encrypted.
- **Scopes** -- defaults to ``openid email offline_access``.

@Leah-BW Leah-BW Nov 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

If offline_access is missing or not granted, no refresh token is issued, and refresh() flags the account as soon as the access token expires.

Suggested change
- **Scopes** -- defaults to ``openid email offline_access``.
- **Scopes** -- defaults to ``openid email offline_access``. Without ``offline_access`` no
refresh token is issued, and users have to reconnect every time the access token expires.


.. note:: Matching is by email domain, case-insensitive but otherwise exact. There can only
be one provider per domain.
Comment on lines +224 to +225

@Leah-BW Leah-BW Nov 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Changes to a provider don't reach accounts that already exist. The server settings are only copied in when the account is created, and refresh looks up the provider by domain, so deleting a provider or changing its domain leaves connected accounts unable to refresh. The only sign of this is a warning in the server log.

Suggested change
.. note:: Matching is by email domain, case-insensitive but otherwise exact. There can only
be one provider per domain.
.. note:: Matching is by email domain, case-insensitive but otherwise exact. There can only
be one provider per domain.
.. warning:: The IMAP and SMTP settings are copied into an account when it is created, so
later changes to a provider do not affect existing accounts. Deleting a provider or changing
its email domain stops token refresh for accounts that are already connected.


**Step 3: Users add their account**

When a user adds a mail account whose address is in a configured domain, Mail pre-fills the
mail servers and opens a consent popup at the identity provider instead of asking for a
password. No password is stored for the account.

Refresh tokens keep the account syncing in the background. If a refresh token is revoked or
expires without being renewed, the affected account is flagged and the user is asked to
reconnect through the same consent popup the next time they open Mail.
Comment on lines +233 to +235

@Leah-BW Leah-BW Nov 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This says more than the code does. In OidcIntegration::refresh(), a rejected refresh only flags the account if token introspection confirms the token is inactive. Other cases that flag it: no refresh token was ever issued, or the stored one can't be decrypted. Without an introspection endpoint (manual mode with the field empty, or a discovery document without introspection_endpoint), the failure is treated as temporary and the account is never flagged. Admins need this to decide whether to set the optional introspection endpoint.

Suggested change
Refresh tokens keep the account syncing in the background. If a refresh token is revoked or
expires without being renewed, the affected account is flagged and the user is asked to
reconnect through the same consent popup the next time they open Mail.
Refresh tokens keep the account syncing in the background. If a refresh is rejected, Mail asks
the identity provider via token introspection (RFC 7662) whether the token is still active.
Only when the provider confirms it is inactive is the account flagged, and the user is asked to
reconnect through the same consent popup the next time they open Mail. Without an introspection
endpoint, a failed refresh is always treated as a temporary error.


Mailbox Share
-------------
Users can share mailboxes with each other. So far, there is no UI for users to change the ACL in the Mail app, but if you want to use it, you need to enable it on the IMAP sever and configure the shares there.
Expand Down
4 changes: 4 additions & 0 deletions user_manual/groupware/mail.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,10 @@ Add a new mail account

.. figure:: images/new-mail-account.png

.. note:: If your administrator has configured single sign-on for your email domain, the
mail servers are pre-filled automatically and you sign in through a consent popup at
your identity provider instead of entering a password.

Change sort order
~~~~~~~~~~~~~~~~~

Expand Down
Loading