Hi! Nice work overall, some hints for some refinements for the next version inline.
On Wed Feb 4, 2026 at 5:13 PM CET, Arthur Bied-Charreton wrote: > Document the new config entries, and add notes/warnings to communicate > that: > > 1. User intervention is required for initial OAuth2 target setup, and > > 2. Microsoft OAuth2 apps *must not* be configured as SPAs by the > user, since it would prevent PVE from automatically extending the > refresh token's lifetime > > Signed-off-by: Arthur Bied-Charreton <[email protected]> > --- > notifications.adoc | 44 ++++++++++++++++++++++++++++++++++++++++---- > 1 file changed, 40 insertions(+), 4 deletions(-) > > diff --git a/notifications.adoc b/notifications.adoc > index 801b327..679b19b 100644 > --- a/notifications.adoc > +++ b/notifications.adoc > @@ -108,16 +108,23 @@ The configuration for SMTP target plugins has the > following options: > * `from-address`: Sets the From-address of the email. SMTP relays might > require > that this address is owned by the user in order to avoid spoofing. The > `From` > header in the email will be set to `$author <$from-address>`. > +* `auth-method`: Sets the authentication method (`plain`, `google-oauth2` or > + `microsoft-oauth2`). > * `username`: Username to use during authentication. If no username is set, > no authentication will be performed. The PLAIN and LOGIN authentication > methods are supported. > * `password`: Password to use when authenticating. > +* `oauth2-client-id`: Client ID for the OAuth2 application, if applicable. > +* `oauth2-client-secret`: Client secret for the OAuth2 application, if > + applicable. > +* `oauth2-tenant-id`: Tenant ID for the OAuth2 application, if applicable. > + Only required for Microsoft OAuth2. > * `mode`: Sets the encryption mode (`insecure`, `starttls` or `tls`). > Defaults > to `tls`. > * `server`: Address/IP of the SMTP relay. > -* `port`: The port to connect to. If not set, the used port . > - Defaults to 25 (`insecure`), 465 (`tls`) or 587 (`starttls`), depending on > - the value of `mode`. > +* `port`: The port to connect to. If not set, the used port defaults to 25 > + (`insecure`), 465 (`tls`) or 587 (`starttls`), depending on the value of > + `mode`. > * `comment`: Comment for this target Thanks for fixing this up, but since this is completely unrelated to your OAuth changes, this should rather be a separate commit (as the first-patch of the pve-docs part of the series - since then it can be applied independently while this series as a whole is still in progress) > > Example configuration (`/etc/pve/notifications.cfg`): > @@ -133,13 +140,42 @@ smtp: example > ---- > > The matching entry in `/etc/pve/priv/notifications.cfg`, containing the > -secret token: > +password: > > ---- > smtp: example > password somepassword > ---- this here as well > > +[[notification_targets_smtp_oauth2]] > +===== OAuth2 Authentication > + > +SMTP targets also support OAuth2 authentication via the XOAUTH2 mechanism for > +Google and Microsoft mail providers. > + > +Setting up OAuth2 authentication requires creating an OAuth2 application with > +the chosen provider. The application must be configured with a redirect URI > +pointing to the {pve} web interface, i.e. the URL from which the initial > +authentication request is performed in the UI. I guess you could also mention that one could add all cluster nodes as permitted origins and redirect URIs. It would also be good to maybe add some concrete examples for sensible origins and redirect URIs, mentioning common restrictions (e.g. Google not allowing IPs) > + > +CAUTION: For Microsoft, the application must *not* be registered as > Single-Page > +Application (SPA), as the lifetime of refresh tokens granted for SPAs cannot > +be extended automatically by {pve}. > + > +To set up OAuth2 authentication via the web interface, select `OAuth2 > (Google)` > +or `OAuth2 (Microsoft)` as the authentication method, fill in the client ID > and > +secret (and the tenant ID for Microsoft), then click the *Authenticate* > button. > +This opens a new window where you can sign in with the selected provider and > +grant the required permissions. Upon successful authentication, a refresh > +token is obtained and stored automatically. > + > +Token refresh happens automatically, manual intervention is only needed if a > +token is revoked. Maybe elaborate what 'manual intervention' means in this case (I assume re-authorize?) . Also could not hurt to mention the pvesh command to trigger a manual token refresh. > + > +NOTE: OAuth2 is currently not configurable through direct configuration file > +editing because the refresh token is managed as dynamic state by {pve}. All > +OAuth2 targets must be configured via the web interface. Maybe mention that one could also add the endpoint by using the appropriate API endoint, supplying a token that they requested by other means. > + > [[notification_targets_gotify]] > Gotify > ~~~~~~
