From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id 12E411FF140 for ; Fri, 24 Apr 2026 10:00:36 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id C5F43C176; Fri, 24 Apr 2026 10:00:32 +0200 (CEST) Date: Fri, 24 Apr 2026 09:59:53 +0200 From: Arthur Bied-Charreton To: Shannon Sterz Subject: Re: [PATCH proxmox-backup v4 23/24] notifications: Add OAuth2 section to SMTP target docs Message-ID: References: <20260421115957.402589-1-a.bied-charreton@proxmox.com> <20260421115957.402589-24-a.bied-charreton@proxmox.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1777017504864 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.775 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 SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [ietf.org,oauth2-redirect.com,yourdomain.com] WEIRD_PORT 0.001 Uses non-standard port number for HTTP WEIRD_QUOTING 0.001 Weird repeated double-quotation marks Message-ID-Hash: EPQDNBNTGXJYBUVCVWRHHWDN3UD64ZML X-Message-ID-Hash: EPQDNBNTGXJYBUVCVWRHHWDN3UD64ZML X-MailFrom: a.bied-charreton@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 CC: pbs-devel@lists.proxmox.com, pve-devel@lists.proxmox.com X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: On Thu, Apr 23, 2026 at 02:24:30PM +0200, Shannon Sterz wrote: > On Tue Apr 21, 2026 at 1:59 PM CEST, Arthur Bied-Charreton wrote: > > Document the new SMTP notification target option, especially that: > > > > 1. User intervention is required for initial setup, and > > > > 2. Microsoft OAuth2 apps *must not* be configured as SPAs by the user, > > since it would prevent PBS from automatically extending the refresh > > token's lifetime. > > > > Signed-off-by: Arthur Bied-Charreton > > --- > > docs/notifications.rst | 102 +++++++++++++++++++++++++++++++++++++++++ > > www/OnlineHelpInfo.js | 12 +++++ > > 2 files changed, 114 insertions(+) > > > > diff --git a/docs/notifications.rst b/docs/notifications.rst > > index 992ef152..935650bb 100644 > > --- a/docs/notifications.rst > > +++ b/docs/notifications.rst > > @@ -69,6 +69,108 @@ address will be used. > > > > See :ref:`notifications.cfg` for all configuration options. > > > > +.. _notification_targets_smtp_oauth2: > > + > > +OAuth2 Authentication > > +""""""""""""""""""""" > > + > > +Proxmox Backup Server supports OAuth2 authentication for SMTP targets via the > > +XOAUTH2 mechanism. This is currently available for Google and Microsoft mail > > +providers. > > + > > +Creating an OAuth2 Application > > +'''''''''''''''''''''''''''''' > > + > > +Before configuring OAuth2 in Proxmox Backup Server, you must register an OAuth2 > > +application with your mail provider: > > + > > +* `Google `_ > > +* `Microsoft Entra ID `_ > > + > > +Choose **Web application** as application type. > > + > > +During registration, add a redirect URI pointing to the Proxmox Backup Server > > +web interface URL from which you will perform the authorization flow, for > > +example: > > + > > +* ``https://pbs1.yourdomain.com:8007`` > > +* ``https://localhost:8007`` > > + > > +You can add multiple redirect URIs to allow the authorization flow to work from > > +any node. > > + > > +.. NOTE:: Google does not allow bare IP addresses as redirect URIs. See > > + :ref:`Google-specific setup ` below > > + for a workaround. > > + > > +Configuring OAuth2 in Proxmox Backup Server > > +''''''''''''''''''''''''''''''''''''''''''' > > + > > +In the web UI, open the notification target's edit panel and select > > +``OAuth2 (Google)`` or ``OAuth2 (Microsoft)`` as the authentication method. > > +Fill in the client ID and secret. For Microsoft, also fill in the tenant ID. > > + > > +Click **Authorize**. This opens a new window where you can sign in with your > > +mail provider and grant the requested permissions. On success, a refresh token > > +is obtained and stored. > > + > > +Token refresh happens automatically, at least once every 24 hours. If the token > > +expires due to extended downtime or is revoked, you will need to re-authorize: > > nit: i think it might be more natural to state what needs to be > re-authorized. so: > > [..], you will need to re-authorize the endpoint: [..] > ACK, will add in v5 > > +open the notification target's edit panel, fill in your client secret, and > > "open" should be capitalized. > ACK, will update that > > +click **Authorize** again. > > + > > +.. NOTE:: OAuth2 cannot be configured through direct configuration file > > + editing. Use the web interface, or alternatively ``proxmox-backup-manager``, > > + to configure OAuth2 targets. Note that when using ``proxmox-backup-manager``, > > + you are responsible for providing the initial refresh token. > > + > > +:: > > + > > + proxmox-backup-manager notification endpoint smtp create oauth2-smtp \ > > + --server smtp.example.com \ > > + --from-address from@gmail.com \ > > + --mailto-user root@pam \ > > + --auth-method google-oauth2 \ > > + --oauth2-client-id \ > > + --oauth2-client-secret \ > > + --oauth2-refresh-token > > + > > +For Microsoft, use ``--auth-method microsoft-oauth2`` and add > > +``--oauth2-tenant-id ``. > > + > > +.. _notification_targets_smtp_oauth2_google: > > + > > +Google > > +'''''' > > + > > +Google does not allow bare IP addresses as redirect URIs. To work around this, > > +add an entry to ``/etc/hosts`` **on the machine where your browser is > > +running**, i.e., your local workstation. > > + > > +:: > > + > > + # Replace with the IP address of your Proxmox Backup Server node > > + local.oauth2-redirect.com > > + > > not sure if that makes sense here. what if the device a user is using > doesn't allow changing the hosts file (e.g. insufficient permissions or > they are using a locked down phone etc.)? > > if we do add this section, consider using a reserved second level domain > instead [1]. using a domain that could be be registered and misused > seems dangerous to me. > > [1]: https://datatracker.ietf.org/doc/html/rfc2606#section-3 > Thanks for the feedback! I am actually unsure if this hack even belongs in our docs now that I think about it again. Maybe it would suffice to just add a warning stating that Google does not allow bare IP addresses and let users figure out how they want to work around that, or even remove it altogether - what do you think? It is not really related to PBS itself after all. > > +You can now register ``https://local.oauth2-redirect.com:8007`` as a redirect > > +URI in your Google OAuth2 application, and use that same URL in the browser > > +when accessing the Proxmox Backup Server web interface to perform the > > +authorization flow. > > + > > +.. _notification_targets_smtp_oauth2_microsoft: > > + > > +Microsoft > > +''''''''' > > + > > +.. WARNING:: For Microsoft, the application must **not** be registered as a > > + Single-Page Application (SPA). Proxmox Backup Server requires long-lived > > + refresh tokens, and Microsoft does not allow extending the lifetime of > > + refresh tokens granted for SPAs. > > + > > +Register your OAuth2 application as a standard **Web** application in the > > +Entra admin center. In addition to the client ID and secret, you will also > > +need the **tenant ID** from your application registration. > > + > > .. _notification_targets_gotify: > > > > Gotify > > diff --git a/www/OnlineHelpInfo.js b/www/OnlineHelpInfo.js > > index 89650cfb..95daed6f 100644 > > --- a/www/OnlineHelpInfo.js > > +++ b/www/OnlineHelpInfo.js > > @@ -251,6 +251,18 @@ const proxmoxOnlineHelpInfo = { > > "link": "/docs/notifications.html#notification-targets-smtp", > > "title": "SMTP" > > }, > > + "notification-targets-smtp-oauth2": { > > + "link": "/docs/notifications.html#notification-targets-smtp-oauth2", > > + "title": "OAuth2 Authentication" > > + }, > > + "notification-targets-smtp-oauth2-google": { > > + "link": "/docs/notifications.html#notification-targets-smtp-oauth2-google", > > + "title": "Google" > > + }, > > + "notification-targets-smtp-oauth2-microsoft": { > > + "link": "/docs/notifications.html#notification-targets-smtp-oauth2-microsoft", > > + "title": "Microsoft" > > + }, > > "notification-targets-gotify": { > > "link": "/docs/notifications.html#notification-targets-gotify", > > "title": "Gotify" >