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

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

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:
+open the notification target's edit panel, fill in your client secret, and
+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
+
+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"
-- 
2.47.3