Secure Email Delivery in Keycloak 26.2 Using XOAUTH2
Email has been one of the oldest and most fundamental services on the internet, used for notifications, password resets, verifications, and more. Over time we’ve seen major improvements — encryption via TLS, then STARTTLS, and now many providers are moving away from basic password authentication in favor of modern token-based schemes like XOAUTH2. With Keycloak 26.2, this evolution has arrived: Keycloak now supports XOAUTH2 for outgoing SMTP mail, adding greater security and compatibility with providers who have deprecated legacy authentication
1. What is XOAUTH2, and Why It Matters
XOAUTH2 is a means of authenticating to an SMTP (or other email-sending) server using an OAuth2 access token rather than a username + password. Some of the key benefits include:
- Improved Security: Tokens can be more tightly controlled, with limited scope and lifetime.
- Compliance with Modern Providers: Many providers are disabling basic auth.
- Centralised and Auditable Auth: Easier management and rotation. Each client’s access can be revoked independently of other clients’ operations.
- Reduced Risk of Credential Leakage: No raw passwords stored or transmitted.
2. How XOAUTH2 is Implemented in Keycloak 26.2
With version 26.2, Keycloak adds native support for XOAUTH2 when sending emails via SMTP. This means administrators can move away from static username and password credentials and instead configure Keycloak to obtain an OAuth2 access token at runtime.
In the Admin Console under Realm → Realm Settings → Email, you can now switch the Authentication Type from Password to Token (XOAUTH2). Once enabled, additional fields appear where you provide:
– Client ID and Client Secret from your identity provider (e.g., Azure AD).
– The OAuth2 Token Endpoint used to request an access token.
– Optional Scopes, depending on your provider (for Microsoft 365: https://outlook.office365.com/.default).
– A From address / SMTP username, which may still be required by the mail server.
Keycloak then handles the process of requesting and refreshing tokens using the Client Credentials Grant flow. You can use the “Test connection” button to verify that the configuration is correct and that emails can be sent successfully.
This approach aligns Keycloak with modern security standards and prepares deployments for providers that are phasing out legacy authentication.
Note: The Enable Debug SMTP option (visible at the bottom of the form) activates extended logging for outgoing email. When enabled, Keycloak produces detailed debug output of the SMTP communication, which can be very useful for diagnosing integration issues such as authentication failures, token retrieval problems, or TLS misconfigurations. It is recommended to use this setting only in testing or troubleshooting scenarios, as it may expose sensitive information in the logs.
Retirement of Basic Authentication for SMTP AUTH (Client Submission) in Exchange Online
3. Why This Matters for Microsoft Azure / Office 365 Users
Microsoft has announced the retirement of Basic Authentication for SMTP AUTH (Client Submission) in Exchange Online. Starting March 1, 2026, Microsoft will begin phasing out Basic Auth, and by April 30, 2026, it will be completely disabled. This change directly impacts Keycloak deployments where outgoing emails are sent via Office 365 / Exchange Online SMTP.
If your Keycloak instance is still configured with a username and password for SMTP, it will stop working once Basic Auth is retired. The solution is to migrate to XOAUTH2 configuration in Keycloak 26.2.
By adopting XOAUTH2, you ensure:
- Continued compatibility with Microsoft email services
- Stronger security and compliance
- Reduced risk compared to static credentials
4. Beyond XOAUTH2?
There’s even more going on in modern email delivery. Many email delivery platforms steer away from traditional SMTP protocol towards API-based approach (e.g. MailJet, SendGrid or MailGun). This gives more flexibility to integrators and allows platform providers to offer additional features. API-based email sending is not jet supported by Keycloak out-of-the-box, but this support can be added via custom extensions. Contact us if you are interested in integrating Keycloak with API-based email delivery platforms.
Conclusion
The addition of XOAUTH2 support in Keycloak 26.2 is more than just a feature upgrade — it’s an essential step for organizations that rely on Office 365, Gmail, or other providers who are deprecating legacy authentication. By adopting XOAUTH2 today, you can future-proof your Keycloak deployment, comply with provider requirements, and improve overall email security.