Keycloak联邦用户在自定义SPI中触发密码重置邮件的问题咨询

方案1：Admin REST API（Postman调用） #

前置配置 #

• 在对应Realm下新建机密（Confidential）类型的Client，开启「服务账号认证」开关
• 进入该Client的「服务账号角色」页面，分配realm-management客户端下的manage-users角色

调用步骤 #

1. 获取接口鉴权Token
   请求方法：POST
   请求地址：http://{Keycloak服务地址}/realms/{Realm名称}/protocol/openid-connect/token
   请求头：Content-Type: application/x-www-form-urlencoded
   请求体参数：

grant_type=client_credentials
client_id=你新建的Client ID
client_secret=你新建的Client密钥

取返回结果中的access_token字段作为后续接口的鉴权凭证。

2. 调用发送动作邮件接口
   请求方法：POST
   请求地址：http://{Keycloak服务地址}/admin/realms/{Realm名称}/users/{目标用户ID}/execute-actions-email
   请求头：

Authorization: Bearer 上一步获取的access_token
Content-Type: application/json

请求体示例：

["UPDATE_PASSWORD"]

可选扩展：URL后可加client_id、redirect_uri查询参数指定用户点击邮件链接后的跳转目标，加lifespan参数指定链接有效时长（单位秒）。
报403排查方向：确认Client已经分配了manage-users角色、目标用户ID属于当前Realm、Token没有过期。

方案2：自定义SPI内Java API调用 #

不需要额外配置管理员权限，直接复用Keycloak内部上下文能力即可实现，示例代码如下：

import org.keycloak.email.EmailTemplateProvider;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.models.UserModel;
import java.util.Collections;
import java.util.List;

// 在你自定义SPI的业务逻辑中调用该方法即可
public void triggerPasswordUpdateEmail(KeycloakSession session, RealmModel currentRealm, UserModel targetUser) {
    // 配置需要用户执行的动作列表，可按需添加VERIFY_EMAIL等其他动作
    List<String> actionList = Collections.singletonList(UserModel.RequiredAction.UPDATE_PASSWORD.name());
    // 参数依次为：动作列表、链接有效期（单位秒，传null使用系统默认值）、目标用户、当前Realm、跳转绑定的Client ID（可选）、跳转地址（可选）
    session.getProvider(EmailTemplateProvider.class)
            .sendExecuteActions(actionList, 86400, targetUser, currentRealm, "你的应用Client ID", "https://你的应用跳转地址");
}

注意：使用前需要确保当前Realm已经配置了可用的SMTP邮件服务器，否则会触发发信异常。

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