SMTP Configuration Guide

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

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

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

Microsoft 365 / Office 365

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

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., [email protected])
• Password: Your Microsoft 365 password or app-specific password
• Enable TLS: 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:
   • Sign in to https://mysignins.microsoft.com/security-info
   • Add method → App password
   • Name it (e.g., “Keycloak SMTP”)
   • Copy the generated 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)

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 TLS: 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)

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 TLS: Optional
• Enable SSL: No

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

Choosing the Right Method

*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 [email protected] | Format-List SmtpClientAuthenticationDisabled

# Enable SMTP AUTH for specific user
Set-CASMailbox -Identity [email protected] -SmtpClientAuthenticationDisabled $false

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 TLS: Yes
• Enable SSL: No

Setup Steps:

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

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

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

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

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

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

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)

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 TLS: Yes
• Enable SSL: No

Setup Steps:

1. If you have 2FA enabled, create an app password:
   • Go to https://account.microsoft.com/security
   • Select “Advanced security options”
   • Under “App passwords”, create a new 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

For organizations using Google Workspace for business email.

Settings:

• SMTP Host: smtp.gmail.com
• Port: 587
• Username: Your full Google Workspace email (e.g., [email protected])
• Password: App-specific password (see setup steps)
• Enable TLS: 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)

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 TLS: 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

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 TLS: 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

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 TLS: 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

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 TLS: 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

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

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

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

*After leaving sandbox mode

Next Steps

• Configure email templates for your brand
• Set up custom domain for better deliverability
• Monitor insights for email and user analytics