Keycloak Client Credentials模式获取Token后调用Introspect API返回401

使用Client Credentials授权类型成功获取Access Token，经jwt.io验证签名和格式均有效，但调用Keycloak的Introspect API时返回401错误，错误信息：

{
    "error": "invalid_request",
    "error_description": "Authentication failed."
}

原错误请求命令：

curl --location --request POST 'https://XXX/realms/YYY/protocol/openid-connect/token/introspect' \
--header 'Authorization: Bearer eyJhbGciOiJS.....' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=eyJhbGciOiJS.....'

核心问题：Introspect API的认证方式错误 #

Keycloak的Introspect API要求调用该API的客户端必须先通过自身凭证完成认证，而非使用待验证的Access Token作为Bearer令牌。这是因为Introspect API的设计目的是让客户端（或资源服务器）向Keycloak验证令牌的有效性，所以调用者本身需要被Keycloak识别为合法客户端。

正确的请求方式 #

使用客户端的client_id和client_secret进行Basic认证，两种实现方式如下：

方式1：用curl -u参数自动生成Basic认证头

curl --location --request POST 'https://XXX/realms/YYY/protocol/openid-connect/token/introspect' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user 'CCC:6yqR3IEE...' \
--data-urlencode 'token=eyJhbGciOiJS.....'

方式2：手动构造Basic认证头

先将client_id:client_secret做Base64编码，再添加到请求头：

# 先执行编码命令：echo -n "CCC:6yqR3IEE..." | base64
curl --location --request POST 'https://XXX/realms/YYY/protocol/openid-connect/token/introspect' \
--header 'Authorization: Basic [替换为Base64编码后的字符串]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=eyJhbGciOiJS.....'

补充说明 #

• jwt.io仅验证令牌的签名算法、格式和声明内容，但无法确认令牌在Keycloak服务器端的状态（如是否被吊销、是否已过期等），Introspect API会实时查询服务器端的令牌状态。
• 默认情况下Keycloak客户端具备调用Introspect API的权限，无需额外配置，只要认证方式正确即可正常返回令牌验证结果。

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