Re: [PATCH proxmox-backup v4 23/24] notifications: Add OAuth2 section to SMTP target docs

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

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 <a.bied-charreton@proxmox.com>
> > ---
> >  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 <https://developers.google.com/identity/protocols/oauth2/web-server>`_
> > +* `Microsoft Entra ID <https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app>`_
> > +
> > +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 <notification_targets_smtp_oauth2_google>` 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 <client ID>                                      \
> > +        --oauth2-client-secret <client secret>                              \
> > +        --oauth2-refresh-token <refresh token>
> > +
> > +For Microsoft, use ``--auth-method microsoft-oauth2`` and add
> > +``--oauth2-tenant-id <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 <IP> with the IP address of your Proxmox Backup Server node
> > +    <IP> 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"
>