[PATCH docs/manager/proxmox{,-perl-rs,-widget-toolkit,-backup} v4 00/24] fix #7238: Add XOAUTH2 authentication support for SMTP notification targets

Arthur Bied-Charreton
2026-04-21T12:00:04Z

This series adds XOAUTH2 support for SMTP notification targets in PVE
and PBS, motivated by Microsoft's upcoming deprecation of basic
authentication for SMTP [0]. Google and Microsoft are supported as
OAuth2 providers.

The main challenge is the OAuth2 refresh tokens management. The
implementations differ from provider to provider, and for Microsoft
specifically, the token needs to be writable by proxmox-notify, since
Microsoft Exchange Online OAuth2 rotates it at every use.

This series solves this by introducing state files. Each SMTP endpoint
gets its own to avoid having to lock all endpoints every time a state
update is made (which can be on every notification for Microsoft
targets). These files are managed entirely from the Rust side.

Tokens are refreshed every time a notification is sent, and proactively
via pveupdate/proxmox-backup-daily-update. State file updates are
atomic (sys::fs::replace_file).

Note that this is technically racy, since multiple notifications could
be sent at the same time from different nodes, but that is okay in
practice given the implementations of the providers we support:

* Google: The token is refreshed in-place, meaning its lifetime is
extended at every use without it being *actually* rotated [1], so no
changes to the state file.
* Microsoft: The token is rotated at each request, however tokens have
a fixed lifetime of 90 days, meaning the old token can still be used.
Concurrent access just means we are letting the last updater win, but
in both cases we end up with a valid token that can be used for
subsequent exchanges [2].

For access token requests in proxmox-notify, the oauth2 crate is used
with a local ureq backend (newtype over ureq::Agent). oauth2's ureq
feature is currently patched out in Debian due to a ureq 2/3 version
mismatch (oauth2 still depends on ureq 2 and Debian only packages ureq
3) [3].

This series requires the following version requirement bumps:
* proxmox-perl-rs -> bumped proxmox-notify
* pve-manager -> bumped proxmox-widget-toolkit and proxmox-perl-rs
* proxmox-backup -> bumped proxmox-widget-toolkit and proxmox-notify

The UI part of the OAuth2 flow is opt-in for consumers, the widget
toolkit may be bumped without bumping all products directly.

Note that this introduces a breaking change in the proxmox-notify API
(new parameter).

Known issues:
- Microsoft OAuth2 support is untested (no test tenant, somehow
impossible to create a free test account). It is implemented by
following the Microsoft Entra ID docs, but there might be something
I overlooked. I would highly appreciate it if someone was able to
test it with their account.

Changes since RFC:
https://lore.proxmox.com/pve-devel/20260213160415.609868-1-a.bied-charreton@proxmox.com/T/#t

Changes since v1:
https://lore.proxmox.com/pve-devel/20260325131444.366808-1-a.bied-charreton@proxmox.com/T/#t

Changes since v2:

proxmox-backup:
* Introduce XOAUTH2 into proxmox-backup

proxmox:
* Make oauth2 and ureq workspace dependencies, and update crates
using them

proxmox-notify:
* Add migration code to {add,update}_endpoint to keep supporting
the old way to set the authentication method for SMTP endpoints
and update old configs.
* Update outdated doc comments in xoauth2::State
* Make xoauth2::State::{load,save,delete} pub instead of pub(crate)
* Guard oauth-related imports and Context trait methods behind smtp
feature flag
* Update state file paths
* Use create_path for recursively creating state file directory in
xoauth2::State::save
* Replace impl From<Option<String>> for State with State::new(String)

proxmox-widget-toolkit:
* Use gettext in OAuth2 handlers' error messages
* Move OAuth2 callback handler to Proxmox.OAuth2

Changes since v3:

proxmox-widget-toolkit:
* Make check for OAuth2 callback stricter to avoid false positives in
case of OpenID login
* Return boolean from OAuth2.handleCallback so caller can branch
accordingly

proxmox-backup:
* Add OAuth2 section to SMTP docs
* Wrap call into proxmox-notify in spawn_blocking
* Avoid entering the OpenID login branch if login is the result of an
OAuth2 calllback

proxmox:
* Remove version from workspace dependencies

[0] https://techcommunity.microsoft.com/blog/exchange/updated-exchange-online-smtp-auth-basic-authentication-deprecation-timeline/4489835
[1] https://developers.google.com/identity/protocols/oauth2#expiration
[2] https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens#token-lifetime
[3] https://git.proxmox.com/?p=debcargo-conf.git;a=blob;f=src/oauth2/debian/patches/disable-ureq.patch;h=828b883a83a86927c5cd32df055226a5e78e8bea;hb=refs/heads/proxmox/trixie

proxmox:

Arthur Bied-Charreton (8):
Add oauth2 and ureq to workspace dependencies
notify: smtp: Introduce xoauth2 module
notify: smtp: Introduce state management
notify: smtp: Factor out transport building logic
notify: smtp: Update API with OAuth2 parameters
notify: smtp: Infer auth method for backwards compatibility
notify: smtp: Add state handling logic
notify: smtp: Add XOAUTH2 authentication support

Cargo.toml | 2 +
proxmox-http/Cargo.toml | 2 +-
proxmox-notify/Cargo.toml | 17 +-
proxmox-notify/debian/control | 68 ++---
proxmox-notify/src/api/common.rs | 16 ++
proxmox-notify/src/api/smtp.rs | 151 +++++++++--
proxmox-notify/src/context/mod.rs | 17 ++
proxmox-notify/src/context/pbs.rs | 23 ++
proxmox-notify/src/context/pve.rs | 25 +-
proxmox-notify/src/context/test.rs | 22 ++
proxmox-notify/src/endpoints/smtp.rs | 241 +++++++++++++++--
proxmox-notify/src/endpoints/smtp/xoauth2.rs | 271 +++++++++++++++++++
proxmox-notify/src/lib.rs | 33 ++-
proxmox-openid/Cargo.toml | 2 +-
14 files changed, 794 insertions(+), 96 deletions(-)
create mode 100644 proxmox-notify/src/endpoints/smtp/xoauth2.rs

proxmox-perl-rs:

Arthur Bied-Charreton (2):
pve-rs: notify: smtp: add OAuth2 parameters to bindings
pve-rs: notify: Add binding for triggering state refresh

common/src/bindings/notify.rs | 78 ++++++++++++-----------------------
1 file changed, 26 insertions(+), 52 deletions(-)

proxmox-widget-toolkit:

Arthur Bied-Charreton (3):
utils: Add OAuth2 flow handlers
utils: oauth2: Add callback handler
notifications: Add opt-in OAuth2 support for SMTP targets

src/Utils.js | 122 ++++++++++++++
src/panel/SmtpEditPanel.js | 280 ++++++++++++++++++++++++++++++---
src/window/EndpointEditBase.js | 1 +
3 files changed, 380 insertions(+), 23 deletions(-)

pve-manager:

Arthur Bied-Charreton (5):
notifications: smtp: api: Add XOAUTH2 parameters
notifications: Add trigger-state-refresh endpoint
notifications: Trigger notification target refresh in pveupdate
login: Handle OAuth2 callback
fix #7238: notifications: smtp: Add XOAUTH2 support

PVE/API2/Cluster/Notifications.pm | 150 +++++++++++++++++++++++++-----
bin/pveupdate | 9 ++
www/manager6/Utils.js | 10 ++
www/manager6/Workspace.js | 2 +
4 files changed, 148 insertions(+), 23 deletions(-)

proxmox-backup:

Arthur Bied-Charreton (5):
notifications: Add XOAUTH2 parameters to endpoints
login: Handle OAuth2 callback
fix #7238: notifications: smtp: Add XOAUTH2 support
daily-update: Refresh OAuth2 state for SMTP notification endpoints
notifications: Add OAuth2 section to SMTP target docs

docs/notifications.rst | 102 ++++++++++++++++++++++++++
src/api2/config/notifications/smtp.rs | 36 ++++++++-
src/bin/proxmox-daily-update.rs | 10 +++
www/Application.js | 4 +-
www/OnlineHelpInfo.js | 12 +++
www/Utils.js | 1 +
6 files changed, 161 insertions(+), 4 deletions(-)

pve-docs:

Arthur Bied-Charreton (1):
notifications: Add OAuth2 section to SMTP targets docs

notifications.adoc | 99 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 99 insertions(+)

Summary over all repositories:
29 files changed, 1608 insertions(+), 198 deletions(-)

--
Generated by murpp 0.11.0