使用Keycloak Java Admin Client测试SMTP连接出现500内部错误

问题描述 #

我通过Keycloak Java Admin Client实现了一个测试SMTP连接的端点，代码如下：

@SneakyThrows
@Override
@PreAuthorize("hasAuthority('" + WRITE_SMTP_CONFIGURATION + "')")
public void testSMTPConfiguration(@RequestBody Map<String, String> smtpConfigurationModel) {
    
    var response = realmService.realm(TenantContext.getTenantId()).testSMTPConnection(smtpConfigurationModel);
    log.info("Test SMTP email status {}", response.getStatus());
}

其中realmService.realm(TenantContext.getTenantId())返回RealmResource对象，调用其testSMTPConnection方法时始终返回500 Internal Server Error。

但在Keycloak后台界面中使用「Test Connection」按钮测试相同的SMTP配置时，却能成功向Gmail账户发送邮件，配置信息如下：

• Server: smtp.gmail.com
• Port: 587
• Start TLS: true
• SSL: false
• Auth: true
• 邮箱/密码

请问为何API调用失败，但界面测试正常？

可能的原因及修复步骤 #

1. 参数键名不匹配 #

Keycloak界面显示的是友好配置名称，但Admin Client API要求传入的参数键名是内部字段名，两者不对应会导致参数解析失败。正确的参数键名对应关系：

• host → 界面的"Server"
• port → 界面的"Port"
• enableStartTls → 界面的"Start TLS"
• ssl → 界面的"SSL"
• auth → 界面的"Auth"
• username → 界面的邮箱账号
• password → 界面的密码
• from → 发件人邮箱（界面测试会自动复用Realm默认发件人，但API调用需显式传入）

2. 参数类型错误 #

你的参数是Map<String, String>，所有值都是字符串类型，但Keycloak的testSMTPConnection方法要求部分参数为非字符串类型：

• port需要是Integer，而非字符串"587"
• enableStartTls、ssl、auth需要是Boolean，而非字符串"true"/"false"

类型不匹配会触发Keycloak内部解析异常，返回500错误。

3. Gmail密码权限问题 #

Gmail要求开启两步验证后使用应用密码登录SMTP，而非原账号密码。如果界面测试用的是应用密码，但API调用传入的是原密码，会导致SMTP认证失败，进而引发500错误。

修复示例代码 #

将参数转换为正确的键名和类型后，代码可调整为：

@SneakyThrows
@Override
@PreAuthorize("hasAuthority('" + WRITE_SMTP_CONFIGURATION + "')")
public void testSMTPConfiguration(@RequestBody Map<String, String> smtpConfigRequest) {
    // 构建符合API要求的参数Map，转换类型并修正键名
    Map<String, Object> smtpConfigurationModel = new HashMap<>();
    smtpConfigurationModel.put("host", smtpConfigRequest.get("Server"));
    smtpConfigurationModel.put("port", Integer.parseInt(smtpConfigRequest.get("Port")));
    smtpConfigurationModel.put("enableStartTls", Boolean.parseBoolean(smtpConfigRequest.get("Start TLS")));
    smtpConfigurationModel.put("ssl", Boolean.parseBoolean(smtpConfigRequest.get("SSL")));
    smtpConfigurationModel.put("auth", Boolean.parseBoolean(smtpConfigRequest.get("Auth")));
    smtpConfigurationModel.put("username", smtpConfigRequest.get("Email"));
    smtpConfigurationModel.put("password", smtpConfigRequest.get("password"));
    // 必须显式传入发件人邮箱
    smtpConfigurationModel.put("from", smtpConfigRequest.get("Email"));
    
    var response = realmService.realm(TenantContext.getTenantId()).testSMTPConnection(smtpConfigurationModel);
    log.info("Test SMTP email status {}", response.getStatus());
}

也可以直接要求前端传入正确键名和类型的JSON参数：

{
  "host": "smtp.gmail.com",
  "port": 587,
  "enableStartTls": true,
  "ssl": false,
  "auth": true,
  "username": "your-email@gmail.com",
  "password": "your-app-password",
  "from": "your-email@gmail.com"
}

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