Zum Inhalt springen

SMTP Configuration Guide

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

Configure SMTP settings to enable email delivery for password resets, email verification, and other notifications in your Keycloak realms.

Overview

Section titled “Overview”

Skycloak supports any SMTP-compatible email service. This guide covers configuration for popular providers including:

  • Microsoft 365 / Office 365
  • Azure Communication Services
  • Google Workspace (formerly G Suite)
  • Gmail
  • SendGrid
  • Amazon SES
  • Mailgun

Common SMTP Settings

Section titled “Common SMTP Settings”

Before configuring your provider, understand these common settings:

  • SMTP Host: The server address for sending emails
  • SMTP Port: Usually 587 (TLS) or 465 (SSL)
  • Username: Your SMTP authentication username
  • Password: Your SMTP authentication password or app-specific password
  • From Email: The email address that appears as the sender
  • From Name: The display name for the sender
  • SSL/TLS: Security protocol settings

Provider Configuration Guides

Section titled “Provider Configuration Guides”

Microsoft 365 / Office 365

Section titled “Microsoft 365 / Office 365”

Microsoft offers multiple SMTP options. Choose based on your needs:

Section titled “Option 1: Authenticated SMTP (Recommended for User Mailboxes)”

Best for: Applications sending email as specific users with Microsoft 365 licenses.

Settings:

  • SMTP Host: smtp.office365.com
  • Port: 587
  • Username: Your full email address (e.g., user@yourdomain.com)
  • Password: Your Microsoft 365 password or app-specific password
  • Enable StartTLS: Yes
  • Enable SSL: No

Setup Steps:

  1. Ensure SMTP AUTH is enabled in Microsoft 365 admin center
  2. For accounts with MFA, create an app password:
  3. Use your email address as username and the app password as password
  4. Verify the mailbox has a valid Microsoft 365 license

Requirements:

  • Microsoft 365 license for the sending account
  • SMTP AUTH must be enabled (check Exchange admin center)
  • No IP restrictions on the account

Option 2: SMTP Relay (Best for Applications)

Section titled “Option 2: SMTP Relay (Best for Applications)”

Best for: Applications and devices that need to send email without per-user licenses. Ideal for Keycloak deployments.

Settings:

  • SMTP Host: smtp.office365.com
  • Port: 587
  • Username: Leave empty (no authentication)
  • Password: Leave empty (no authentication)
  • Enable StartTLS: Yes
  • Enable SSL: No
  • From Email: Any address in your verified domains

Setup Steps:

  1. Create a Connector in Exchange Admin Center:

    • Sign in to Exchange admin center
    • Go to Mail flow → Connectors
    • Click “+ Add a connector”
    • From: “Your organization’s email server”
    • To: “Microsoft 365”
    • Name it (e.g., “Keycloak SMTP Relay”)

  2. Configure Authentication:

    • Choose “By verifying that the IP address…”
    • Add your Keycloak server’s static IP address
    • This IP must be static and dedicated

  3. Set Security Restrictions:

    • Reject messages if not encrypted: Yes (recommended)
    • Reject messages if not from your domains: Yes

  4. Update SPF Records: Add your server IP to SPF:

    v=spf1 ip4:YOUR_SERVER_IP include:spf.protection.outlook.com -all

  5. Test the Connector:

    • Use the built-in test in Exchange admin center
    • Send a test email from Keycloak

Advantages:

  • No per-user licensing required
  • Higher sending limits (10,000 messages/day)
  • Simpler credential management
  • Better for automated/system emails

Limitations:

  • Requires static IP address
  • Can only send from verified domains
  • Cannot send to external recipients unless they’re in your directory

Option 3: Direct Send (Simple but Limited)

Section titled “Option 3: Direct Send (Simple but Limited)”

Best for: Internal notifications only (cannot send to external recipients).

Settings:

  • SMTP Host: Your MX endpoint (e.g., yourdomain-com.mail.protection.outlook.com)
  • Port: 25
  • Username: None
  • Password: None
  • Enable StartTLS: Optional
  • Enable SSL: No

Note: This method is very limited and not recommended for Keycloak.

Option 4: OAuth / XOAUTH2 Authentication (Keycloak 26.2+)

Section titled “Option 4: OAuth / XOAUTH2 Authentication (Keycloak 26.2+)”

Best for: Organizations that have disabled basic SMTP authentication and require modern OAuth 2.0 authentication. Available on Keycloak 26.2 and later.

Prerequisites:

  • Keycloak version 26.2.0 or later on your cluster
  • Azure AD (Microsoft Entra ID) app registration
  • SMTP.SendAsApp application permission (under “Office 365 Exchange Online”) with admin consent
  • The app registered in Exchange Online and granted access to the sending mailbox

Settings:

  • SMTP Host: smtp.office365.com
  • Port: 587
  • Enable StartTLS: Yes
  • Enable SSL: No
  • Authentication Method: OAuth / XOAUTH2 (select in Skycloak UI)
  • Username: The mailbox email address (e.g., noreply@yourdomain.com)
  • Token URL: https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token
  • Scope: https://outlook.office365.com/.default
  • Client ID: Your Azure AD Application (client) ID
  • Client Secret: Your Azure AD client secret value

Setup Steps:

  1. Register an Azure AD App:

    • Go to Microsoft Entra ID
    • Click “New registration”
    • Name: e.g., “Keycloak SMTP OAuth”
    • Supported account types: “Accounts in this organizational directory only”
    • Click “Register”
    • Note the Application (client) ID and Directory (tenant) ID

  2. Add API Permission:

    • In your app registration, go to “API permissions”
    • Click “Add a permission” → “APIs my organization uses” → search for Office 365 Exchange Online (not Microsoft Graph)
    • Choose “Application permissions”
    • Search for and select SMTP.SendAsApp
    • Click “Add permissions”
    • Click “Grant admin consent for [your organization]”

  3. Create Client Secret:

    • Go to “Certificates & secrets”
    • Click “New client secret”
    • Add description and expiry
    • Copy the secret value immediately (it won’t be shown again)

  4. Configure in Skycloak:

    • Go to Email → SMTP Configuration
    • Select your provider or configure manually
    • Choose “OAuth / XOAUTH2” authentication method
    • Enter your Token URL (replace {your-tenant-id} with your actual tenant ID)
    • Enter the scope, client ID, and client secret
    • Save and test

Common Mistakes:

  • Adding Microsoft Graph’s SMTP.Send instead of SMTP.SendAsApp under “Office 365 Exchange Online” (the Graph permission does not cover app-only SMTP submission)
  • Skipping the Exchange Online registration (New-ServicePrincipal + Add-MailboxPermission, see the PowerShell section below)
  • Using https://graph.microsoft.com/.default as scope instead of https://outlook.office365.com/.default (the SMTP scope must be the Outlook one)
  • Forgetting to grant admin consent after adding the SMTP.Send permission
  • Using the client secret ID instead of the secret value
  • Not replacing {tenant-id} placeholder in the Token URL with your actual Azure AD tenant ID

Troubleshooting:

  • “AUTHENTICATE failed”: Verify the SMTP.Send permission has admin consent
  • “535 5.7.3 Authentication unsuccessful”: Check the Token URL contains your real tenant ID
  • Token endpoint errors: Ensure the client secret hasn’t expired
  • Mailbox not found: The username (mailbox email) must have an Exchange Online license

Choosing the Right Method

Section titled “Choosing the Right Method”
Method Best For Licensing External Recipients Setup Complexity
Authenticated SMTP User-specific emails Required Yes Easy
SMTP Relay Applications/Keycloak Not required Yes* Medium
Direct Send Internal only Not required No Easy
OAuth / XOAUTH2 Modern auth required Required Yes Medium

*With proper connector configuration

Troubleshooting Microsoft 365 SMTP:

  • Authentication failures: Check if SMTP AUTH is disabled organization-wide
  • “5.7.57 Client not authenticated”: SMTP AUTH may be disabled for the user
  • “5.7.60 SMTP client does not have permissions”: Check connector IP configuration
  • Rate limiting: Microsoft 365 has a 30 messages/minute limit for authenticated SMTP
  • SPF failures: Ensure your server IP is in the SPF record

PowerShell Commands for Admins:

# Check if SMTP AUTH is enabled globally
Get-TransportConfig | Format-List SmtpClientAuthenticationDisabled

# Enable SMTP AUTH globally (if disabled)
Set-TransportConfig -SmtpClientAuthenticationDisabled $false

# Check SMTP AUTH for specific user
Get-CASMailbox -Identity user@domain.com | Format-List SmtpClientAuthenticationDisabled

# Enable SMTP AUTH for specific user
Set-CASMailbox -Identity user@domain.com -SmtpClientAuthenticationDisabled $false

# For OAuth (SMTP.SendAsApp): register the app's service principal in
# Exchange Online and grant it the sending mailbox. Use the Enterprise
# Application's Object ID (not the app registration's).
New-ServicePrincipal -AppId <application-client-id> -ObjectId <enterprise-app-object-id>
Add-MailboxPermission -Identity noreply@yourdomain.com -User <enterprise-app-object-id> -AccessRights FullAccess

Azure Communication Services

Section titled “Azure Communication Services”

Azure Communication Services provides reliable email delivery with built-in analytics. Important: SMTP authentication requires creating an Entra (Azure AD) application.

Settings:

  • SMTP Host: smtp.azurecomm.net
  • Port: 587
  • Username: <ACS_Resource_Name>.<Application_ID>.<Tenant_ID>
  • Password: Your Entra app client secret (not the ACS access key)
  • Enable StartTLS: Yes
  • Enable SSL: No

Setup Steps:

Step 1: Create Azure Communication Services Resource

Section titled “Step 1: Create Azure Communication Services Resource”
  1. Sign in to Azure Portal
  2. Create a new Azure Communication Services resource
  3. Note the resource name (e.g., myacsresource) - you’ll need this for the username

Step 2: Configure Email Domain

Section titled “Step 2: Configure Email Domain”
  1. In your ACS resource, go to Email → Domains
  2. Click “Connect domain” or “Add domain”
  3. Choose between:
    • Azure managed domain: Quick setup with *.azurecomm.net address
    • Custom domain: Use your own domain (requires DNS verification)
  4. For custom domains:
    • Add the provided TXT record to verify ownership
    • Configure SPF and DKIM records as shown
    • Wait for verification (can take up to 30 minutes)

Step 3: Register an Entra Application

Section titled “Step 3: Register an Entra Application”
  1. Go to Microsoft Entra ID (formerly Azure Active Directory)
  2. Navigate to App registrations → New registration
  3. Configure the application:
    • Name: e.g., “ACS SMTP Authentication”
    • Supported account types: “Accounts in this organizational directory only”
    • Redirect URI: Leave empty (not needed for SMTP)
  4. Click Register
  5. On the overview page, note:
    • Application (client) ID: e.g., 12345678-1234-1234-1234-123456789012
    • Directory (tenant) ID: e.g., 87654321-4321-4321-4321-210987654321

Step 4: Create Client Secret

Section titled “Step 4: Create Client Secret”
  1. In your Entra app, go to Certificates & secrets
  2. Click New client secret
  3. Add a description (e.g., “SMTP Authentication”)
  4. Choose expiry (recommendation: 12 or 24 months)
  5. Click Add
  6. Important: Copy the secret value immediately - it won’t be shown again!

Step 5: Grant API Permissions

Section titled “Step 5: Grant API Permissions”
  1. In your Entra app, go to API permissions
  2. Click Add a permission
  3. Select APIs my organization uses
  4. Search for “Azure Communication Services”
  5. Select Azure Communication Services
  6. Choose Delegated permissions
  7. Select user_impersonation
  8. Click Add permissions
  9. If you’re an admin, click Grant admin consent (otherwise ask your admin)

Step 6: Build Your SMTP Credentials

Section titled “Step 6: Build Your SMTP Credentials”

Username Format: <ACS_Resource_Name>.<Application_ID>.<Tenant_ID>

Example:

  • ACS Resource Name: myacsresource
  • Application ID: 12345678-1234-1234-1234-123456789012
  • Tenant ID: 87654321-4321-4321-4321-210987654321
  • Username: myacsresource.12345678-1234-1234-1234-123456789012.87654321-4321-4321-4321-210987654321

Password: The client secret value from Step 4

Step 7: Configure in Skycloak

Section titled “Step 7: Configure in Skycloak”
  1. Go to your realm’s SMTP settings
  2. Enter:
    • SMTP Host: smtp.azurecomm.net
    • Port: 587
    • Username: The formatted username from Step 6
    • Password: The client secret from Step 4
    • From Email: Must match your verified domain
    • Enable StartTLS: Yes
  3. Save and test the configuration

Troubleshooting Azure Communication Services SMTP:

  • “5.7.3 Authentication unsuccessful”:
    • Verify the username format is exactly <resource>.<appId>.<tenantId>
    • Ensure no extra spaces or characters
    • Resource name is case-sensitive
  • “Client was not authenticated”:
    • Check that API permissions were granted
    • Verify admin consent was provided if required
    • Ensure the client secret hasn’t expired
  • “Invalid client secret provided”:
    • You may have copied the secret ID instead of the value
    • Generate a new client secret if needed
  • “Sender address not verified”:
    • The From email must match a verified domain
    • Check domain verification status in ACS Email settings
  • SPF/DKIM failures:
    • Verify DNS records match exactly as shown in Azure
    • Allow 24-48 hours for DNS propagation

Important Notes:

  • The Entra app username format is different from the old endpoint/access key method
  • Client secrets expire - set a reminder to rotate before expiry
  • Each Entra app can have multiple client secrets for rotation
  • Monitor usage in Azure Portal under ACS → Metrics

Outlook.com (Personal Accounts)

Section titled “Outlook.com (Personal Accounts)”

For personal Microsoft accounts (Outlook.com, Hotmail, Live.com).

Settings:

  • SMTP Host: smtp-mail.outlook.com
  • Port: 587
  • Username: Your full email address
  • Password: Your password or app-specific password
  • Enable StartTLS: Yes
  • Enable SSL: No

Setup Steps:

  1. If you have 2FA enabled, create an app password:
  2. Use your email address as username
  3. Use the app password (if 2FA) or regular password

Note: This is for personal accounts only. For business accounts, use Microsoft 365/Office 365 settings above.

Google Workspace

Section titled “Google Workspace”

For organizations using Google Workspace for business email.

Settings:

  • SMTP Host: smtp.gmail.com
  • Port: 587
  • Username: Your full Google Workspace email (e.g., user@company.com)
  • Password: App-specific password (see setup steps)
  • Enable StartTLS: Yes
  • Enable SSL: No

Setup Steps:

  1. Enable 2-factor authentication for your Google Workspace account
  2. Go to Google Account Security
  3. Under “2-Step Verification”, select “App passwords”
  4. Generate a new app password for “Mail”
  5. Use this 16-character password in SMTP configuration

Note: Less secure app access is deprecated. Always use app-specific passwords.

Gmail (Personal Accounts)

Section titled “Gmail (Personal Accounts)”

For development or testing with personal Gmail accounts.

Settings:

  • SMTP Host: smtp.gmail.com
  • Port: 587
  • Username: Your Gmail address
  • Password: App-specific password (required)
  • Enable StartTLS: Yes
  • Enable SSL: No

Setup Steps:

  1. Enable 2-factor authentication on your Gmail account
  2. Visit Google App Passwords
  3. Select “Mail” and your device
  4. Copy the generated 16-character password
  5. Use this password in your SMTP configuration

Important: Gmail has sending limits (500 emails/day for personal accounts).

SendGrid

Section titled “SendGrid”

A popular transactional email service with high deliverability.

Settings:

  • SMTP Host: smtp.sendgrid.net
  • Port: 587
  • Username: apikey (literal string)
  • Password: Your SendGrid API key
  • Enable StartTLS: Yes
  • Enable SSL: No

Setup Steps:

  1. Create a SendGrid account and verify your email
  2. Navigate to Settings > API Keys
  3. Create a new API key with “Mail Send” permissions
  4. Use “apikey” as username and the API key as password
  5. Verify your sender domain for better deliverability

Amazon SES

Section titled “Amazon SES”

Amazon’s scalable email service, ideal for AWS users.

Settings:

  • SMTP Host: email-smtp.[region].amazonaws.com (e.g., email-smtp.us-east-1.amazonaws.com)
  • Port: 587
  • Username: Your SMTP username (not your AWS access key)
  • Password: Your SMTP password (not your AWS secret key)
  • Enable StartTLS: Yes
  • Enable SSL: No

Setup Steps:

  1. Enable SES in your AWS region
  2. Verify your domain or email address
  3. Navigate to SES > SMTP Settings
  4. Create SMTP credentials (creates an IAM user)
  5. Use the generated SMTP username and password
  6. Request production access to remove sandbox limitations

Mailgun

Section titled “Mailgun”

Developer-friendly email service with powerful APIs.

Settings:

  • SMTP Host: smtp.mailgun.org (US) or smtp.eu.mailgun.org (EU)
  • Port: 587
  • Username: Your Mailgun SMTP username (usually your domain)
  • Password: Your Mailgun SMTP password
  • Enable StartTLS: Yes
  • Enable SSL: No

Setup Steps:

  1. Sign up for Mailgun and add your domain
  2. Verify your domain with DNS records
  3. Navigate to Sending > Domain settings > SMTP credentials
  4. Create SMTP credentials for your domain
  5. Use the provided username and password

Security Best Practices

Section titled “Security Best Practices”
  1. Use App-Specific Passwords: Never use your main account password
  2. Enable TLS/SSL: Always use encrypted connections
  3. Verify Sender Domains: Improves deliverability and prevents spoofing
  4. Monitor Sending Limits: Each provider has different limits
  5. Use Dedicated IPs: For high-volume sending (available with some providers)
  6. Regular Key Rotation: Update API keys and passwords periodically

Testing Your Configuration

Section titled “Testing Your Configuration”

After configuring SMTP:

  1. Save your SMTP settings in Skycloak
  2. Use the “Test SMTP” button to send a test email
  3. Check your inbox and spam folder
  4. Review any error messages in the UI

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”

Authentication Failed

  • Verify username and password are correct
  • Check if app-specific password is required
  • Ensure account has SMTP permissions enabled

Connection Timeout

  • Verify SMTP host and port are correct
  • Check firewall rules allow outbound SMTP
  • Try alternate ports (587, 465, 25)

Emails Going to Spam

  • Configure SPF, DKIM, and DMARC records
  • Use a verified sender domain
  • Avoid spam trigger words in content

Rate Limiting

  • Check provider’s sending limits
  • Implement email queuing for bulk sends
  • Consider upgrading your plan

Provider Comparison

Section titled “Provider Comparison”
Provider Free Tier Deliverability Setup Complexity Best For
Gmail 500/day Good Easy Development
Google Workspace Varies Excellent Easy Business email
Microsoft 365 (Auth) Varies by plan Excellent Easy Business with M365
Microsoft 365 (Relay) No extra cost Excellent Medium Applications/Keycloak
SendGrid 100/day Excellent Medium Production apps
Amazon SES 62,000/month* Excellent Complex AWS users
Azure Comm Services Pay-as-you-go Excellent Medium Azure users
Mailgun 1,000/month Excellent Medium Developers

*After leaving sandbox mode

Next Steps

Section titled “Next Steps”
© 2026 Skycloak. Alle Rechte vorbehalten. Design von Yasser SolimanKeycloak™ is a trademark of the Linux Foundation. Skycloak is not affiliated with the Keycloak project.