Keycloak忘记密码功能配置后测试邮件发送失败求助

Hey there, let's work through this common Keycloak + Gmail SMTP issue together. The generic "Failed to send email" error usually traces back to authentication or configuration mismatches—here are the most likely fixes to try out:

1. Use a Gmail App Password (Critical for 2FA-enabled Accounts) #

If your Gmail account has two-factor authentication (2FA) turned on (which is recommended for security), your regular account password won't work in Keycloak. You need to generate a dedicated App Password instead:

• Head to your Google Account > Security > Under "Signing in to Google", select App Passwords (this option only appears if 2FA is enabled)
• Choose "Mail" as the app, and "Other (custom name)" as the device (e.g., "Keycloak Auth")
• Copy the generated 16-character App Password, then paste it into the "Password" field in Keycloak's Realm Email settings.

2. Verify SSL Port and Configuration Match #

Double-check these settings are exactly correct:

• Host: smtp.gmail.com (no typos!)
• Port: 465 (this is the correct port for SSL connections)
• Ensure the Enable SSL checkbox is ticked, and Username/Password Authentication is turned on. Sometimes settings fail to save properly, so try re-saving the configuration after confirming.

3. Check "Less Secure Apps" (Only for Non-2FA Accounts) #

If you don't have 2FA enabled (not recommended), Gmail blocks third-party app access by default. You'll need to enable "Less secure app access" in your Google Account > Security > Less secure app access. Note: This option is being phased out for most accounts, so using an App Password is the better long-term solution.

4. Dig Into Keycloak Logs for Exact Errors #

The generic error message doesn't give enough detail. Check Keycloak's server logs to find the root cause:

• For standalone Keycloak: Look in standalone/log/server.log
• For containerized Keycloak: Run docker logs <your-keycloak-container-name> to pull logs
  Search for terms like "SMTP", "email", or "javax.mail" to spot specific issues (e.g., "Invalid credentials" confirms a password problem, "Connection refused" points to network blocks).

5. Test Network Connectivity from Keycloak Server #

Make sure your Keycloak server can reach Gmail's SMTP server on port 465. Run these commands on the server to verify:

• telnet smtp.gmail.com 465 (should connect successfully without errors)
• openssl s_client -connect smtp.gmail.com:465 (should show a valid SSL handshake)
  If either command fails, your server's firewall or network is blocking outbound traffic on port 465—work with your ops team to open this port.

6. Check for Gmail Account Restrictions #

Gmail sometimes temporarily restricts accounts with unusual activity (e.g., new accounts, logins from unfamiliar locations). Log into your Gmail web account to see if there are pending verification prompts or notifications about sending limits.

内容的提问来源于stack exchange，提问作者Oumaima