Sending Mails via SMTP and XOAUTH2 authentication mechanism

Closes #17432 Signed-off-by: Sebastian Rose <sebastian.rose@gmail.com>
2026-05-07 23:50:03 -05:00 · 2024-11-14 21:09:27 +01:00
parent ed809d7884
commit 4fb1c41155
26 changed files with 1000 additions and 115 deletions
@@ -41,4 +41,83 @@ Encryption::
  Tick one of these checkboxes to support sending emails for recovering usernames and passwords, especially if the SMTP server is on an external network. You will most likely need to change the *Port* to 465, the default port for SSL/TLS.

 Authentication::
-  Set this switch to *ON* if your SMTP server requires authentication. When prompted, supply the *Username* and *Password*. The value of the *Password* field can refer a value from an external <<_vault-administration,vault>>.
+  Set this switch to *ON* if your SMTP server requires authentication.
+
+Username::
+  All authentication-mechanisms require a username.
+
+Authentication Type::
+  Choose the kind of authentication: 'password' or 'token'.
+
+Password::
+  Only needed when *Authentication Type* 'password' is selected.
+  Supply the *Password*. The value of the *Password* field can refer a value from an external <<_vault-administration,vault>>.
+
+Auth Token URL::
+  Only needed when *Authentication Type* 'token' is selected.
+  Supply the *Auth Token URL* that is used to fetch a token via client credentials grant.
+
+Auth Token Scope::
+  Only needed when *Authentication Type* 'token' is selected.
+  Supply the *Auth Token Scope* that is used to fetch a token from the *Auth Token URL*.
+
+Auth Token ClientId::
+  Only needed when *Authentication Type* 'token' is selected.
+  Supply the *Auth ClientId* that is used to fetch a token from the *Auth Token URL*.
+
+Auth Token Client Secret::
+  Only needed when *Authentication Type* 'token' is selected.
+  Supply the *Auth Client Secret* that authenticates the client to fetch a token from the *Auth Token URL*. The value of the *Auth Client Secret* field can refer a value from an external <<_vault-administration,vault>>.
+
+== Configuration for Microsoft Azure and Office365
+
+Microsoft Azure allows 'Client Credentials Grant' using a client secret to gather an access token.
+Microsoft Office365 supports SMTP with XOAUTH2 to authenticate with the gathered token.
+
+Links to relevant Microsoft documentation:
+
+- https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac[Usage of role base access control for applications in exchange online]
+- Settings in https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth[Authenticate an IMAP, POP or SMTP connection using OAuth]
+
+The following way setting up keycloak to send mails with Azure and Office365 has been verified by a test.
+There might be other variants to achieve the same depending on your environment.
+
+From::
+`<some>@<domain>`
+
+Host::
+`smtp.office365.com`
+
+Port::
+`587`
+
+Encryption::
+Check Start TLS
+
+Username::
+`<some>@<domain>` (might be the same of a different value than the sender value)
+
+Auth Token Url::
+`+https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token+`
+
+Replace TenantID with the id of your Microsoft tenant, usually a UUID, in Azure or just copy the token url from the list of endpoints displayed in the Azure Console.
+
+Auth Token Scope::
+`+https://outlook.office.com/.default+`
+
+Auth Token ClientId::
+`<ApplicationId>`
+
+Replace ApplicationId with the id of your application in Azure, usually a UUID.
+
+Auth Token ClientSecret::
+`<Secret configured>`
+
+== Configuration for Google Mail
+
+Not supported by Keycloak yet, because Google decided to not allow client-secrets for the Client Credentials Grant.
+
+== Configuration for AWS
+
+XOAUTH2 is not supported by the AWS-SMTP service.
+The AWS-service requires to use a password.