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 F33661FF13F for ; Thu, 23 Apr 2026 14:25:15 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 1D24E15AAF; Thu, 23 Apr 2026 14:25:11 +0200 (CEST) Mime-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=UTF-8 Date: Thu, 23 Apr 2026 14:24:30 +0200 Message-Id: Subject: Re: [PATCH proxmox-backup v4 23/24] notifications: Add OAuth2 section to SMTP target docs To: "Arthur Bied-Charreton" , , X-Mailer: aerc 0.20.0 References: <20260421115957.402589-1-a.bied-charreton@proxmox.com> <20260421115957.402589-24-a.bied-charreton@proxmox.com> In-Reply-To: <20260421115957.402589-24-a.bied-charreton@proxmox.com> From: "Shannon Sterz" X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1776946981620 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.120 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: IUIRVPXNWGDTDUXTDFGC3ZS5622ZCUWK X-Message-ID-Hash: IUIRVPXNWGDTDUXTDFGC3ZS5622ZCUWK X-MailFrom: s.sterz@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: 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 vi= a 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 S= erver > +web interface URL from which you will perform the authorization flow, fo= r > +example: > + > +* ``https://pbs1.yourdomain.com:8007`` > +* ``https://localhost:8007`` > + > +You can add multiple redirect URIs to allow the authorization flow to wo= rk 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 meth= od. > +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 th= e token > +expires due to extended downtime or is revoked, you will need to re-auth= orize: 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: [..] > +open the notification target's edit panel, fill in your client secret, a= nd "open" should be capitalized. > +click **Authorize** again. > + > +.. NOTE:: OAuth2 cannot be configured through direct configuration file > + editing. Use the web interface, or alternatively ``proxmox-backup-man= ager``, > + to configure OAuth2 targets. Note that when using ``proxmox-backup-ma= nager``, > + 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 nod= e > + 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 > +You can now register ``https://local.oauth2-redirect.com:8007`` as a red= irect > +URI in your Google OAuth2 application, and use that same URL in the brow= ser > +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 a= s a > + Single-Page Application (SPA). Proxmox Backup Server requires long-li= ved > + refresh tokens, and Microsoft does not allow extending the lifetime o= f > + refresh tokens granted for SPAs. > + > +Register your OAuth2 application as a standard **Web** application in th= e > +Entra admin center. In addition to the client ID and secret, you will al= so > +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 =3D { > "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-g= oogle", > + "title": "Google" > + }, > + "notification-targets-smtp-oauth2-microsoft": { > + "link": "/docs/notifications.html#notification-targets-smtp-oauth2-m= icrosoft", > + "title": "Microsoft" > + }, > "notification-targets-gotify": { > "link": "/docs/notifications.html#notification-targets-gotify", > "title": "Gotify"