Keycloak OAuth SMTP Configuration

• Overview
• ✅ Prerequisites
• 🔧 Step-by-Step Configuration
  • Create App with OAuth2 in Entra ID
  • 🧭 Configure SMTP with OAuth2 in Keycloak

Overview #

Starting from version Keycloak 26+, Keycloak supports OAuth2-based SMTP authentication. This configuration is essential when using mail providers that have deprecated basic authentication (e.g., Microsoft Entra ID / Gmail).

This document provides step-by-step instructions to configure Keycloak 26 for sending emails over SMTP using OAuth 2.0 in Office365.

✅ Prerequisites #

Before starting, ensure you have:

• A Keycloak 26+ instance deployed ).
• A valid OAuth2 client application configured on your email provider:
  • For Microsoft: Entra ID → App Registrations.

🔧 Step-by-Step Configuration #

Create App with OAuth2 in Entra ID #

1. Sign in to the Microsoft Entra ID.
2. Click App registrations on the left menu.
3. Click New registration.
4. Register the Application with the following data:
   1. Name: Keycloak SMTP OAuth.
   2. Supported account types: My organization only.
   3. Click Register to finish.
5. Create a Client Secret
   1. In the newly created app, go to Certificates & secrets.
   2. Under Client secrets, click + New client secret.
   3. Add a description like SMTP OAuth for Keycloak, choose expiry duration, and click Add.
   4. Copy the client secret value immediately (it won’t be shown again).
6. Assign API Permissions
   1. Go to API Permissions → Click + Add a permission.
   2. Choose APIs my organization uses.
   3. Search for and select Office 365 Exchange Online.
   4. Click Application permissions.
   5. Expand the section and select the following:
      1. IMAP.AccessAsApp
      2. Mail.Read
      3. Mail.ReadWrite
      4. Mail.Send
      5. Mailbox.Settings.ReadWrite
      6. POP.AccessAsApp
      7. SMTP.SendAsApp
   6. Click Add Permissions.
   7. Back on the permissions page, click Grant admin consent.

🔒Store the client secret securely (e.g., Vault, Kubernetes Secret).

🧭 Configure SMTP with OAuth2 in Keycloak #

1. Log in to the Keycloak Admin Console.
2. Navigate to Realm Settings from the left-hand menu.
3. Click the Email tab.
4. Fill in the following fields in the Email settings page:

Field	Value
Host	smtp.office365.com
Port	587
Encryption	StartTLS
Authentication	token
Username	support@reframe-data.io
Auth Token URL	https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
Auth Token Scope	https://outlook.office365.com/.default
Auth Token ClientId	<application-client-id>
Auth Token Client Secret	<application-client-secret-value>

5. Save the Email Settings.
6. Click the Test Connection button and verify that test email is send.