From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id AC09D1FF13B for ; Wed, 11 Feb 2026 11:05:49 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id C000117C0A; Wed, 11 Feb 2026 11:06:30 +0100 (CET) Mime-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=UTF-8 Date: Wed, 11 Feb 2026 11:06:24 +0100 Message-Id: From: "Lukas Wagner" To: "Arthur Bied-Charreton" , Subject: Re: [PATCH pve-docs 1/1] notifications: Add section about OAuth2 to SMTP targets docs X-Mailer: aerc 0.21.0-0-g5549850facc2-dirty References: <20260204161354.458814-1-a.bied-charreton@proxmox.com> <20260204161354.458814-16-a.bied-charreton@proxmox.com> In-Reply-To: <20260204161354.458814-16-a.bied-charreton@proxmox.com> X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1770804298846 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.036 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_VALIDITY_CERTIFIED_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_RPBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_SAFE_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: IDKXUBQZPMMBPRK3FYT7LPKPF2OWWRJV X-Message-ID-Hash: IDKXUBQZPMMBPRK3FYT7LPKPF2OWWRJV X-MailFrom: l.wagner@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 > --- > 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 f= ollowing 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. Th= e `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 s= et, > no authentication will be performed. The PLAIN and LOGIN authenticatio= n > methods are supported. > * `password`: Password to use when authenticating. > +* `oauth2-client-id`: Client ID for the OAuth2 application, if applicabl= e. > +* `oauth2-client-secret`: Client secret for the OAuth2 application, if > + applicable. > +* `oauth2-tenant-id`: Tenant ID for the OAuth2 application, if applicabl= e. > + Only required for Microsoft OAuth2. > * `mode`: Sets the encryption mode (`insecure`, `starttls` or `tls`). De= faults > 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`), dependi= ng 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) > =20 > Example configuration (`/etc/pve/notifications.cfg`): > @@ -133,13 +140,42 @@ smtp: example > ---- > =20 > The matching entry in `/etc/pve/priv/notifications.cfg`, containing the > -secret token: > +password: > =20 > ---- > smtp: example > password somepassword > ---- this here as well > =20 > +[[notification_targets_smtp_oauth2]] > +=3D=3D=3D=3D=3D OAuth2 Authentication > + > +SMTP targets also support OAuth2 authentication via the XOAUTH2 mechanis= m 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 Sing= le-Page > +Application (SPA), as the lifetime of refresh tokens granted for SPAs ca= nnot > +be extended automatically by {pve}. > + > +To set up OAuth2 authentication via the web interface, select `OAuth2 (G= oogle)` > +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 refres= h > +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 > ~~~~~~