Keycloak测试邮件连接报Could not convert socket to TLS如何解决

该报错是Keycloak与SMTP邮件服务器建立TLS加密连接时握手失败导致，常见触发原因包括：邮件服务器使用的TLS协议版本不被Keycloak运行的JDK默认支持、邮件TLS配置参数不匹配、邮件服务器自签名证书未被JDK信任、SSL与StartTLS配置冲突。

对应报错日志：Could not convert socket to TLS

• 校准邮件基础配置
  进入Keycloak对应Realm的Realm Settings→Email页面，核对以下配置：

  • 端口为587时，仅勾选Enable StartTLS，不要勾选Enable SSL
  • 端口为465时，仅勾选Enable SSL，不要勾选Enable StartTLS
  • 临时测试可勾选Skip SSL Certificate Validation跳过证书校验，确认配置无问题后生产环境再替换为证书导入方案
    修改后先重新测试连接，若仍报错再执行后续步骤。

• 调整JDK TLS禁用策略
  找到Keycloak运行所使用的JDK安装目录，编辑jre/lib/security/java.security文件，定位到jdk.tls.disabledAlgorithms配置项，删除该配置中包含的TLSv1、TLSv1.1相关条目，保存文件后重启Keycloak服务，适配仍使用低版本TLS协议的邮件服务器。

• 导入邮件服务器证书到JDK信任库（生产环境推荐）

  • 执行命令导出邮件服务器证书：
    openssl s_client -connect <你的SMTP服务器地址>:<端口> < /dev/null | sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' > smtp.crt
  • 执行命令将证书导入JDK信任库，默认信任库密码为changeit：
    keytool -import -alias smtp-cert -file smtp.crt -keystore $JAVA_HOME/jre/lib/security/cacerts
  • 导入完成后重启Keycloak服务即可。

• Quarkus版Keycloak额外配置
  若你使用的是Quarkus发行版的高版本Keycloak，编辑conf/keycloak.conf配置文件，添加以下参数：

spi-email-smtp-starttls-enabled=true
spi-email-smtp-ssl-protocols=TLSv1.2 TLSv1.3
# 如需跳过证书校验可添加下行
spi-email-smtp-trust-all=true

保存配置后重启Keycloak服务。

内容的提问来源于stack exchange，提问作者siemasiema123.96