OAuth2 令牌内省代理

它解决什么问题

当 API 收到 Authorization: Bearer ... 时，资源服务器往往需要回答三个问题：令牌是否仍有效、允许访问哪些 scope、目标资源是否在 aud 中。只解析 JWT payload 会在签名信任、撤销状态、短期有效令牌和不透明令牌面前失手。这个技能把校验职责交给符合 RFC 7662 的内省端点，并与 Keycloak、Auth0、Okta 的内省 API 对接，适合需要在请求路径上实时核验 claims、scopes 与过期时间的运维和安全场景。

核心能力与关键步骤

1. 提取 bearer token：从请求头或 proxy 上游请求中取出访问令牌，避免把完整凭证写入日志。
2. 调用内省端点：按环境配置把令牌交给 Keycloak、Auth0 或 Okta 的 introspection API，实时获取令牌状态。
3. 核验活跃状态与过期时间：检查 active、exp、iat 等标准声明，判断令牌是否仍可访问受保护资源。
4. 校验 audience 与 scopes：确认 aud 覆盖当前 API 或资源标识；解析 scope 这一空格分隔字符串，并与 API 所需权限集合做交集判断。
5. 返回决策与上下文：把允许、拒绝以及必要 claim 传递给调用方，便于记录审计和返回 401/403。

适用边界与注意点

• 适合资源服务器能可靠访问 IdP 内省端点、且信任该 IdP 作实时判定的情况；网络故障、超时和缓存策略会影响可用性。
• 对标准 JWT validation 已解码 payload 的场景，仍需继续检查 aud 等标准声明；本技能补足的是对内省响应中 claims、scopes 和过期状态的核验。
• IdP access tokens 不需要在业务侧再验证，应交给签发它的 IdP 处理。
• 不要把令牌、内省响应或客户端秘密写入日志；scope 名称、audience 和资源标识要先在 API 与 IdP 侧约定清楚。