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

[Arthur Bied-Charreton <a.bied-charreton@proxmox.com>]

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


[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                   | 116 +++++++++++++++
 src/panel/SmtpEditPanel.js     | 263 +++++++++++++++++++++++++++++++--
 src/window/EndpointEditBase.js |   1 +
 3 files changed, 367 insertions(+), 13 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 (4):
  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

 src/api2/config/notifications/smtp.rs | 36 ++++++++++++++++++++++++---
 src/bin/proxmox-daily-update.rs       |  9 +++++++
 www/Application.js                    |  2 ++
 www/Utils.js                          |  1 +
 4 files changed, 45 insertions(+), 3 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:
  27 files changed, 1479 insertions(+), 187 deletions(-)

-- 
Generated by murpp 0.11.0