Secure email delivery with XOAUTH2

May 18 2025 by Sebastian Rose

Keycloak relies on email functionality for tasks like password resets, user verifications, and notifications.

A common setup is for Keycloak to authenticate to the SMTP server with a username and password. With issue #17432, the Keycloak community raised the need for token-based authentication with XOAUTH2, as some providers deprecated the authentication for SMTP with passwords.

With Keycloak 26.2, the SMTP AUTH configuration now supports XOAUTH2. As Keycloak’s role is that of an application, it uses the client credentials grant to fetch the token. The SMTP AUTH configuration in Keycloak now supports all required fields to fetch such a token with client id and client secret.

When implementing this functionality, I found that while it works with Microsoft Azure and Office365, it would need a different mechanism for providers like Google.

So let’s follow through this example, and then discuss if we need something different from SMTP altogether.

Configuring Keycloak to send emails with XOAUTH2

The following assumes that you are working with Keycloak 26.2.

In a realm, navigate to Realm Settings → Email and fill in the fields.

To see the new XOAUTH2 feature, enable Authentication via the radio-button and switch the Authentication Type from Password to Token. You can find further details in the documentation on sending emails.

Settings for token based authentication

Once you fill all the settings for gathering an access token and the username, you can test the configuration via the built-in "Test connection" button.

Challenges with real world cloud providers

Testing Microsoft Azure, I found it supports fetching an XOAUTH2 token through a client credentials grant using a client secret. It needs several configuration changes in several places on Microsoft Azure to make it work, which is annoying, but eventually it all works in Keycloak 26.2.

Google does not support the client credentials grant with a client secret, but requires sending a JWT token. Therefore, it does not work with Keycloak 26.2 yet, as that would need additional functionality and even more configuration options for Keycloak. Please vote on issue #39610 to add Google with SMTP and XOAUTH2 to a future Keycloak release.

When analyzing the Google APIs, we found that a Google Enterprise account seems to have no possibility of restricting the sender email address. So any email address, even the CEO’s email address, could be as a sender with Google and XOAUTH2 authentication, which feels wrong.

Looking at the different capabilities of those two cloud providers, it raises the question of how to support scenarios for additional providers: Should Keycloak show provider-specific configuration screens, or would we need to make the UI even more generic and complex?

Re-thinking sending messages to users

While implementing XOAUTH2, I learned a lot more details on a modern cloud-provider’s perspective handle sending of emails. Another big impulse came from discussions during the Keycloak DevDay 2025 Hackathon.

Let’s break apart what happens when we talk about the current email functionality of Keycloak:

  • Keycloak is sending a message to an identity. This message could be any format, and building a message could be separated from the actual delivery of that message.

  • An identity could have all kinds of message handles and email just one of them. Also, the way to send an email in a cloud world might no longer be the Simple Mail Transfer Protocol (SMTP), but an HTTP- and JSON-based API.

To me, working with SMTP and XOAUTH2 feels like working on something quite ancient. So what might be other steps for the bright future of Keycloak regarding sending messages to identities?

Providers offer HTTP-based messaging APIs to send email without using SMTP. Looking at these and remembering the discussions from the Keycloak DevDay 2025 Hackathon:

  • Why use email addresses at all?

  • All kinds of handles could reach an identity.

  • In some parts of the planet, only mobile phones are used to reach out to somebody.

  • In development scenarios, even a chat-message to, for example, Slack might be enough.

I started a discussion about the Future of sending messages to identities in Keycloak. Please join the discussion and let me know what you think.