适用版本： 7.x-8.x
1. 错误异常的基本描述 #
Failed to exchange code for Id Token. Code=[...]; Description=[...] 表示 Elasticsearch 已经调用了 OpenID Connect 提供方的 Token Endpoint，但提供方返回了标准 OAuth2 错误响应。
常见现象 #
- 浏览器完成回调后登录失败。
- Elasticsearch 日志中除了主异常外，还会带出 IdP 返回的错误码和描述。
- 常见返回包括
invalid_grant、invalid_client、unauthorized_client、invalid_request。
2. 为什么会发生这个错误 #
从日志上下文看，Elasticsearch 能成功解析 Token Endpoint 的错误响应，并把 code 与 description 原样写入异常消息。这说明失败点不在本地解析，而在 IdP 明确拒绝了本次授权码交换。
常见原因包括：
- 授权码已过期、已被使用，或回调中的 code 与当前会话不匹配。
client_id、client_secret、redirect_uri与 IdP 注册配置不一致。- IdP 不允许当前客户端以授权码流程换取 ID Token。
3. 如何排查和解决这个异常和解决这个异常 #
- 先查看异常里的
Code和Description，这是最直接的根因线索。 - 核对 realm 配置中的
rp.client_id、客户端认证方式和redirect_uri。 - 检查 IdP 侧应用注册，确认授权码流程与当前回调地址已启用。
- 如果错误是
invalid_grant，重点排查授权码是否重复使用或过期。
4. 如何解决这个错误 #
常用修复思路 #
- 修正客户端凭据、回调地址和授权范围配置。
- 确保浏览器回调落在与发起登录同一会话上下文中。
- 缩短代理链路和人为跳转，避免授权码过期或被篡改。
5. 小结 #
这个异常已经把 IdP 的拒绝原因暴露出来，排查时应优先根据 Code 和 Description 精确修复，而不是泛化为“网络故障”。
相关错误 #
附：日志上下文 #
if (tokenSuccessResponse.indicatesSuccess() == false) {
final TokenErrorResponse errorResponse = TokenErrorResponse.parse(tokenHttpResponse);
tokensListener.onFailure(new ElasticsearchSecurityException(
"Failed to exchange code for Id Token. Code=[{}]; Description=[{}]",
errorResponse.getErrorObject().getCode(),
errorResponse.getErrorObject().getDescription()
));
}
