跳到主要内容

2. 内省端点 (Introspection Endpoint)

内省端点是一个 OAuth 2.0 端点, 它接收表示 OAuth 2.0 令牌的参数, 并返回一个 JSON [RFC7159] 文档, 表示围绕该令牌的元信息, 包括此令牌当前是否处于活动状态. 活动令牌的定义取决于授权服务器, 但通常是指由该授权服务器签发, 未过期, 未被吊销, 并且可在发起内省调用的受保护资源处使用的令牌.

内省端点必须由第 4 节所述的传输层安全机制保护. 受保护资源如何发现内省端点的位置不在本规范范围内.

2.1. 内省请求 (Introspection Request)​

受保护资源使用 HTTP POST [RFC7231] 请求调用内省端点, 参数按 [W3C.REC-html5-20141028] 定义作为 application/x-www-form-urlencoded 数据发送. 受保护资源会发送一个表示令牌的参数, 以及可选参数; 这些可选参数表示受保护资源已知的附加上下文, 用于帮助授权服务器生成响应.

token : 必需. 令牌的字符串值. 对访问令牌而言, 这是 OAuth 2.0 [RFC6749] 第 5.1 节中定义的令牌端点返回的 "access_token" 值. 对刷新令牌而言, 这是 OAuth 2.0 [RFC6749] 第 5.1 节中定义的令牌端点返回的 "refresh_token" 值. 其他令牌类型不在本规范范围内.

token_type_hint : 可选. 关于提交进行内省的令牌类型的提示. 受保护资源可以传递此参数, 以帮助授权服务器优化令牌查找. 如果服务器无法使用给定提示定位令牌, 它必须把搜索扩展到其支持的所有令牌类型. 授权服务器可以忽略此参数, 尤其是在它能够自动检测令牌类型时. 此字段的值定义在 OAuth Token Revocation [RFC7009] 中定义的 "OAuth Token Type Hints" 注册表中.

内省端点可以接受其他可选参数, 以向查询提供进一步上下文. 例如, 授权服务器可能希望知道访问受保护资源的客户端 IP 地址, 以判断呈现令牌的是否可能是正确客户端. 此参数或任何其他参数的定义不在本规范范围内, 应由服务文档或本规范扩展定义. 如果授权服务器在没有附加信息的情况下无法确定令牌状态, 它应当返回一个内省响应, 按第 2.2 节所述指示该令牌不活动.

为了防止令牌扫描攻击, 端点还必须要求某种形式的授权才能访问该端点, 例如 OAuth 2.0 [RFC6749] 中描述的客户端认证, 或单独的 OAuth 2.0 访问令牌, 例如 OAuth 2.0 Bearer Token Usage [RFC6750] 中描述的 bearer 令牌. 管理和验证这些认证凭据的方法不在本规范范围内.

例如, 以下内容展示受保护资源调用令牌内省端点来查询 OAuth 2.0 bearer 令牌. 受保护资源使用单独的 OAuth 2.0 bearer 令牌来授权此调用.

以下是一个非规范性请求示例:

POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483

token=2YotnFZFEjr1zCsicMWpAA

在此示例中, 受保护资源使用客户端标识符和客户端密钥向内省端点认证自身. 受保护资源还发送一个令牌类型提示, 指示它正在查询访问令牌.

以下是一个非规范性请求示例:

POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=mF_9.B5f-4.1JqM&token_type_hint=access_token

2.2. 内省响应 (Introspection Response)​

服务器以 application/json 格式返回一个 JSON 对象 [RFC7159], 其中包含以下顶层成员.

active : 必需. 布尔指示符, 表示所呈现的令牌当前是否活动. 令牌 "active" 状态的具体含义会随授权服务器实现及其保存的令牌信息而变化, 但 "active" 属性返回 "true" 通常表示给定令牌已由此授权服务器签发, 未被资源所有者吊销, 并且位于其给定有效时间窗口内 (例如, 在签发时间之后且过期时间之前). 关于实现这类检查的信息见第 4 节.

scope : 可选. 一个 JSON 字符串, 包含与此令牌相关联的作用域列表, 以空格分隔, 格式见 OAuth 2.0 [RFC6749] 第 3.3 节.

client_id : 可选. 请求此令牌的 OAuth 2.0 客户端的客户端标识符.

username : 可选. 授权此令牌的资源所有者的人类可读标识符.

token_type : 可选. OAuth 2.0 [RFC6749] 第 5.1 节中定义的令牌类型.

exp : 可选. 整数时间戳, 以自 1970 年 1 月 1 日 UTC 起经过的秒数度量, 表示此令牌何时过期, 如 JWT [RFC7519] 中所定义.

iat : 可选. 整数时间戳, 以自 1970 年 1 月 1 日 UTC 起经过的秒数度量, 表示此令牌最初何时签发, 如 JWT [RFC7519] 中所定义.

nbf : 可选. 整数时间戳, 以自 1970 年 1 月 1 日 UTC 起经过的秒数度量, 表示此令牌在何时之前不得使用, 如 JWT [RFC7519] 中所定义.

sub : 可选. 令牌主体, 如 JWT [RFC7519] 中所定义. 通常是授权此令牌的资源所有者的机器可读标识符.

aud : 可选. 服务特定的字符串标识符或字符串标识符列表, 表示此令牌的预期受众, 如 JWT [RFC7519] 中所定义.

iss : 可选. 表示此令牌签发者的字符串, 如 JWT [RFC7519] 中所定义.

jti : 可选. 令牌的字符串标识符, 如 JWT [RFC7519] 中所定义.

具体实现可以用自身服务特定的响应名称扩展此结构, 作为该 JSON 对象的顶层成员. 打算跨域使用的响应名称必须注册到第 3.1 节定义的 "OAuth Token Introspection Response" 注册表中.

授权服务器可以对发出相同请求的不同受保护资源作出不同响应. 例如, 授权服务器可以限制为每个受保护资源返回给定令牌中的哪些作用域, 以防止受保护资源了解超出其运行所需的更大网络信息.

受保护资源可以缓存响应以提高性能并降低内省端点负载, 但代价是受保护资源用于作出授权决策的信息实时性降低. 关于缓存响应时的权衡, 见第 4 节.

例如, 以下响应包含一组关于活动令牌的信息:

以下是一个非规范性响应示例:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "active": true,
 "client_id": "l238j323ds-23ij4",
 "username": "jdoe",
 "scope": "read write dolphin",
 "sub": "Z5O3upPC88QrAjx00dis",
 "aud": "https://protected.example.net/resource",
 "iss": "https://server.example.com/",
 "exp": 1419356238,
 "iat": 1419350238,
 "extension_field": "twenty-seven"
}

如果内省调用已被正确授权, 但令牌不活动, 在此服务器上不存在, 或受保护资源不允许内省此特定令牌, 则授权服务器必须返回一个内省响应, 其中 "active" 字段设置为 "false". 注意, 为避免向第三方披露过多授权服务器状态, 授权服务器不应包含关于非活动令牌的任何附加信息, 包括令牌为何不活动.

以下是一个已被吊销或因其他原因无效的令牌的非规范性响应示例:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "active": false
}

2.3. 错误响应 (Error Response)​

如果受保护资源使用 OAuth 2.0 客户端凭据向内省端点认证, 且其凭据无效, 授权服务器会按 OAuth 2.0 [RFC6749] 第 5.2 节所述返回 HTTP 401 (Unauthorized).

如果受保护资源使用 OAuth 2.0 bearer 令牌来授权其对内省端点的调用, 且用于授权的令牌不包含足够权限或对该请求而言因其他原因无效, 授权服务器会按 OAuth 2.0 Bearer Token Usage [RFC6750] 第 3 节所述返回 HTTP 401 代码.

注意, 对非活动或因其他原因无效的令牌 (或受保护资源不被允许知晓的令牌) 发出的格式正确且已授权查询, 在本规范中不被视为错误响应. 在这些情况下, 授权服务器必须改为返回一个内省响应, 其中 "active" 字段按第 2.2 节所述设置为 "false".

最后于 更新