Keycloak非主领域无法调用execute-actions-email API求助

排查方向1：检查目标领域的管理客户端状态 #

• 确认非主领域内的admin-cli客户端已启用：进入目标领域的「Clients」页面，找到admin-cli，确保「Enabled」开关处于开启状态。
• 若使用自定义管理客户端，需同步确认该客户端已启用，且「Settings」中「Access Type」设置为confidential或public（匹配你的使用场景）。

排查方向2：验证令牌的目标领域权限 #

• 主领域令牌默认仅对主领域拥有管理权限，跨领域操作需确保令牌包含目标领域的管理角色：
  1. 在主领域的「Clients」中找到用于获取令牌的客户端，进入「Scope」标签，添加目标领域的realm-management客户端角色（如manage-users、view-users等必要权限）。
  2. 重新获取令牌，通过jwt.io解析令牌，确认resource_access字段中包含目标领域的权限声明。

排查方向3：确认请求端点路径正确性 #

Keycloak 21.1的管理API路径已移除/auth前缀，需确保非主领域请求的端点格式正确：

curl --location --request PUT 'http://<your_ip>:<your_port>/admin/realms/<target_realm>/users/<user_id>/execute-actions-email' \
--header 'Authorization: Bearer <my_token>' \
--header 'Content-Type: application/json' \
--data '["UPDATE_PASSWORD"]'

避免路径中残留/auth前缀，这是新版本API的常见错误点。

排查方向4：检查目标领域的邮件动作配置 #

• 进入目标领域的「Realm Settings」→「Email」→「Actions」，确认「Execute Actions Email」相关配置未被禁用，对应模板存在且正常。
• 检查领域的「Required Actions」中，UPDATE_PASSWORD是否已启用（即使请求中指定该动作，领域层面禁用仍会导致异常）。

排查方向5：排查客户端跨领域访问设置 #

• 在主领域的客户端设置中，确认「Access Settings」里的「Valid Redirect URIs」「Web Origins」包含目标领域相关配置，确保跨领域请求的客户端被允许。
• 若使用服务账户执行操作，需确认服务账户在目标领域中已被授予对应管理角色，而非仅在主领域授权。

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