[PATCH pve-docs v5 27/27] notifications: add OAuth2 section to SMTP targets docs

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

Document the new config entries and the requirements to use XOAUTH2 for SMTP
notification targets, 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 <a.bied-charreton@proxmox.com>
---
 notifications.adoc | 88 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)

diff --git a/notifications.adoc b/notifications.adoc
index ea8fc75..33b1230 100644
--- a/notifications.adoc
+++ b/notifications.adoc
@@ -108,10 +108,17 @@ The configuration for SMTP target plugins has the following 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.  The `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 set,
   no authentication will be performed. The PLAIN and LOGIN authentication
   methods are supported.
 * `password`: Password to use when authenticating.
+* `oauth2-client-id`: Client ID for the OAuth2 application, if applicable.
+* `oauth2-client-secret`: Client secret for the OAuth2 application, if
+  applicable.
+* `oauth2-tenant-id`: Tenant ID for the OAuth2 application, if applicable.
+  Only required for Microsoft OAuth2.
 * `mode`: Sets the encryption mode (`insecure`, `starttls` or `tls`). Defaults
   to `tls`.
 * `server`: Address/IP of the SMTP relay.
@@ -140,6 +147,87 @@ smtp: example
         password somepassword
 ----
 
+[[notification_targets_smtp_oauth2]]
+==== OAuth2 Authentication
+
+{pve} 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 {pve}, you must register an OAuth2 application
+with your mail provider:
+
+* https://developers.google.com/identity/protocols/oauth2/web-server[Google]
+* https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app[Microsoft Entra ID]
+
+Choose *Web application* as application type.
+
+During registration, add a redirect URI pointing to the {pve} web interface
+URL from which you will perform the authorization flow, for example:
+
+* `https://pve1.example.com:8006`
+* `https://localhost:8006`
+
+You can add multiple redirect URIs to allow the authorization flow to work from
+any cluster node.
+
+NOTE: Google does not allow bare IP addresses as redirect URIs. If you need to
+work around this, specify a dummy domain as the redirect URI and make sure that
+your local machine resolves it to the proper IP address (by, for example, adding
+a line to `/etc/hosts`).
+
+===== Configuring OAuth2 in {pve}
+
+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.
+
+NOTE: For OAuth2 targets, the configured `from-address` is also used as the SMTP
+authentication identity, so it must match the mailbox authorized with the
+provider.
+
+Token refresh happens automatically, at least once every 24 hours. If the token
+expires due to extended cluster downtime or is revoked, you will need to
+re-authorize the endpoint: 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 `pvesh`, to configure OAuth2 targets. Note
+that when using `pvesh`, you are responsible for providing the initial refresh
+token.
+
+----
+pvesh create /cluster/notifications/endpoints/smtp \
+    --name oauth2-smtp                             \
+    --server smtp.example.com                      \
+    --from-address from@example.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_microsoft]]
+===== Microsoft
+
+WARNING: For Microsoft, the application must *not* be registered as a
+Single-Page Application (SPA). {pve} 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
 ~~~~~~
-- 
2.47.3