Keycloak introspect与userinfo端点调用返回401未授权问题排查

针对introspect端点的配置检查 #

• 启用客户端令牌内省权限：在Keycloak客户端设置的Advanced标签下，找到「Allow Token Introspection」选项并开启，这是调用introspect接口的必要前提。
• 修正令牌类型提示：你当前传入的token_type_hint为requesting_party_token，如果你的令牌是从/openid-connect/token获取的普通access token，应改为access_token，类型不匹配会直接导致校验失败。修改后的代码示例：

Form formData = new Form();
formData.param("client_id", clientID);
formData.param("client_secret", clientSecret);
formData.param("token_type_hint", "access_token");
formData.param("token", token);

• 确认客户端访问类型：客户端的「Access Type」必须设置为confidential，只有该类型的客户端才能通过client_id+client_secret的方式完成接口认证，public类型客户端无法使用此方式调用introspect接口。

针对userinfo端点的配置检查 #

• 校验令牌scope：获取access token时，必须请求profile、email等userinfo接口所需的scope，即使JWT中包含scope字段，若未包含对应权限，仍会返回401。
• 验证令牌有效性：检查令牌是否过期、签名是否合法、受众（aud字段）是否与当前客户端ID完全匹配，可通过Keycloak客户端设置内的JWT解码工具直接验证。
• 确认客户端协议：确保客户端使用的是openid-connect协议，userinfo是OIDC标准端点，非OIDC客户端无法正常调用。

通用配置排查 #

• Realm令牌设置：检查Realm的「Token Settings」页面，确认OIDC相关功能已正常启用，比如「OpenID Connect Compatibility Mode」配置符合你的需求。
• 网络链路检查：若请求经过代理或网关，需确认请求头中的Authorization字段未被篡改、introspect接口的表单参数未被截断。

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