Traefik OAuth 2.0 Token Introspection 中间件：基于 RFC 7662 的令牌校验与声明级授权配置指南

本文基于本仓库文档 docs/content/reference/routing-configuration/http/middlewares/oauth2-token-introspection.md 展开。该文档介绍的 OAuth 2.0 Token Introspection（令牌内省）认证中间件用于让 API 网关调用 OAuth 2.0 授权服务器（IdP）的 Token Introspection 扩展端点，实时获取访问令牌（access token）的元数据与有效状态，并依据返回的声明（claims）对请求做细粒度授权、向业务后端转发用户身份信息。读完本文，你将掌握：该中间件的完整 CRD 配置方法、全部配置项的含义与默认值、声明校验表达式（Equals/Prefix/OneOf 等）的写法、TLS 与 Kubernetes Secret 凭据引用方式，以及它与本项目其他认证中间件的适用边界。

本仓库是开源版 Traefik Proxy（Cloud Native Application Proxy）的完整代码库，其中 features 对比文档 明确指出：Traefik Hub API Gateway 是在 Traefik Proxy 之上叠加企业级安全、分布式能力与高级访问控制的产品形态。本文所讲解的 OAuth 2.0 Token Introspection 中间件即属于这类仅在 Traefik Hub API Gateway 中提供的高级特性——文档标题下方的 !!! info "Traefik Hub Feature" 提示块对此有明确声明。它在本仓库中是以中间件参考文档 + Kubernetes CRD 配置清单的形态沉淀的，声明位置为 spec.plugin.oAuthIntrospection，即采用插件（plugin）式中间件的配置模式。

一、中间件定位与工作原理

1.1 什么是 OAuth 2.0 Token Introspection

RFC 7662（Token Introspection）定义了一种机制：受保护资源（这里是 Traefik Hub API Gateway）在无法自行解析令牌内容时，可向授权服务器上的 Introspection 端点提交令牌，换取该令牌的结构化元数据（典型字段包括 active、scope、client_id、username、token_type、exp、iat、nbf、sub、aud、iss、jti，以及令牌内嵌的其它声明）。

本中间件正是这一流程的落地实现：

• 从客户端请求中提取令牌；
• 携带客户端凭据调用 IdP 的 introspection 端点；
• 根据端点返回的元数据判断令牌是否 active；
• 用返回的 claims 执行声明的条件校验（若配置了 claims）；
• 校验通过后将请求放行到后端应用，并可把声明值写入转发头、从访问日志中回填用户名。

1.2 一次请求的完整校验链路

从配置结构（tokenSource → clientConfig → claims/forwardHeaders/forwardAuthorization/usernameClaim）可以清晰还原其内部处理顺序：

1. 令牌提取：中间件按 tokenSource 中定义的来源（请求头、Authorization 头 + 认证 scheme、查询参数、Cookie）取出访问令牌；
2. 令牌内省：以 clientConfig 定义的端点 URL、请求头、超时与重试策略、TLS 参数，将令牌发给授权服务器的 introspection 端点，并可选带上 token_type_hint 提示令牌类型；
3. 状态裁决：若内省结果显示令牌无效（例如 active=false）或授权服务器调用失败，请求被拒绝（返回 401 Unauthorized 一类的认证失败响应）；
4. 声明授权：当 claims 配置了表达式时，按表达式逐项比对内省响应中的 claims，条件不满足则拒绝请求；
5. 身份传递：校验通过后，若配置了 forwardHeaders，则把指定 claims 的值写入转发给后端的新请求头；forwardAuthorization 决定原始 Authorization 头是保留还是剥离；usernameClaim 指定的 claim 用于填充访问日志的 clientusername 字段。

文档还特别给出了一条重要约束：claims、forwardHeaders、usernameClaim 三个能力只能作用于 JWT 格式的令牌——因为只有 JWT 能把任意自定义声明带进内省响应，普通不透明令牌（opaque token）的内省响应只包含 RFC 7662 定义的标准顶层字段。

二、完整配置示例（CRD）

在 Kubernetes 中，该中间件声明为 traefik.io/v1alpha1 的 Middleware CRD，主体放在 spec.plugin.oAuthIntrospection 之下。下面是文档给出的完整示例（注释为额外补充说明）：

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      tokenSource:
        header: Authorization
        headerAuthScheme: Bearer
      clientConfig:
        url: "https://YOUR-KEYCLOAK-ADDRESS/realms/YOUR-REALM/protocol/openid-connect/token/introspect"
        headers:
          Authorization: Basic ZXhhbXBsZTpleGFtcGxl # echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64
        tokenTypeHint: access_token
      forwardHeaders:
        Group: grp
        Expires-At: exp
      claims: Equals(`grp`, `admin`)

示例要点解读：

• tokenSource.header / headerAuthScheme 指示从请求的 Authorization 头中读取 Bearer 前缀后的令牌，这是最常见的令牌传递方式；
• clientConfig.url 指向授权服务器的 introspection 端点。示例使用的是 Keycloak 的标准 introspection 地址形态 .../protocol/openid-connect/token/introspect，其中的 KEYCLOAK-ADDRESS 与 YOUR-REALM 需要替换为实际值；
• 由于大多数 IdP 要求调用 introspection 端点时提供客户端身份，示例通过 clientConfig.headers 预置了 Authorization: Basic <base64> 请求头。注释给出了生成方式：echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64；
• claims: Equals(\grp`, `admin`)表示仅当令牌内省结果携带grp=admin` 时放行，这是典型的“组级授权”写法；
• forwardHeaders 则把 claims 中 grp、exp 的值分别转发为 Group、Expires-At 请求头，供后端服务做进一步业务判断。

需要说明的是，示例中的 Keycloak 地址仅用于演示配置形态，具体 introspection 端点路径由你的 IdP 决定，以授权服务器官方文档为准。

三、配置选项总览

文档以参数表形式给出了该中间件的全部配置项，下表完整整理其字段、描述、默认值与是否必填：

字段	说明	默认值	必填
claims	定义用于授权放行判定的一组声明校验规则，仅适用于 JWT 格式令牌（详见下文“claims 声明校验”一节）	""	否
clientConfig.url	introspection 端点 URL，必须包含 scheme 与路径	""	是
clientConfig.headers	每次 introspection 请求都会携带的请求头。取值可以是普通字符串，也可以是合法的 Go template；模板内可访问与当前被内省请求对应的 Request 变量	""	否
clientConfig.tokenTypeHint	被内省令牌的类型提示，作为 hint 发送给内省服务器（RFC 7662 术语）	""	否
clientConfig.tls.ca	PEM 编码的证书包，或引用证书包的 URN，用于与授权服务器建立 TLS 连接	""	否
clientConfig.tls.cert	PEM 编码的客户端证书，或引用证书的 URN，用于与授权服务器建立 TLS 连接	""	否
clientConfig.tls.key	PEM 编码的客户端私钥，或引用私钥的 URN，用于与授权服务器建立 TLS 连接	""	否
clientConfig.tls.insecureSkipVerify	与授权服务器通信时禁用 TLS 证书校验。便于测试，但强烈不建议生产环境使用	false	否
clientConfig.timeoutSeconds	放弃访问授权服务器请求之前的等待时间	5	否
clientConfig.maxRetries	对授权服务器失败请求的重试次数	3	否
forwardAuthorization	请求通过中间件校验后，Authorization 头是被转发给后端还是被剥离	false	否
forwardHeaders	需要附加到请求上的 HTTP 头，值取自授权服务器返回的令牌 claims。未在 JWT 中找到对应 claim 时，转发头为空值。仅适用于 JWT 格式令牌	[]	否
tokenSource.header	包含客户端所发令牌的请求头名称。tokenSource 相关选项至少需设置一项	""	否
tokenSource.headerAuthScheme	当请求头名为 Authorization 时使用的认证 scheme（如 Bearer）	""	否
tokenSource.query	包含客户端所发令牌的查询参数名。tokenSource 至少需设置一项	""	否
tokenSource.cookie	包含客户端所发令牌的 Cookie 名。tokenSource 至少需设置一项	""	否
usernameClaim	用于在访问日志中回填 clientusername 的 claim。仅适用于 JWT 格式令牌	""	否

几个值得强调的语义：

• clientConfig.url 是全配置中唯一的必填项，其它均为可选；
• tokenSource 的四个子项虽然默认值与必填列都标记为“否”，但整体约束是“至少设置其中一项”，否则中间件无从取到令牌；
• 对外通信的健壮性默认值集中在 clientConfig：超时 5 秒、失败重试 3 次。对于放在网关热路径上的认证校验来说，合理调低超时、控制重试可避免授权服务器故障时对整体请求延迟造成过大冲击；
• clientConfig.headers 支持 Go template，模板上下文提供了 Request（即被内省的原请求）变量，可用于把动态信息注入内省请求头，例如按客户端来源携带不同的上下文标识。

四、claims：声明级条件授权

claims 允许把“令牌里必须有什么样的声明”以表达式形式表达，实现比单纯校验 active=true 更细的授权。它独立成节，是因为该表达式的函数集、布尔组合规则与嵌套取值规则需要专门掌握。

4.1 支持的函数

函数	说明	示例
Equals	校验 key 的值与 value 相等	Equals(\grp`, `admin`)`
Prefix	校验 key 的值以 value 为前缀	Prefix(\referrer`, `http://example.com`)`
Contains（字符串）	校验 key 的值包含 value	Contains(\referrer`, `/foo/`)`
Contains（数组）	校验 key 所指向的数组包含 value	Contains(\areas`, `home`)`
SplitContains	将 key 的值按指定分隔符拆分后，判断拆分结果中是否包含 value	SplitContains(\scope`, ` `, `writer`)`
OneOf	校验 key 指向的数组包含 values 中的任意一个	OneOf(\areas`, `office`, `lab`)`

其中 SplitContains 尤其适合 OAuth scope 场景：很多授权服务器的 scope claim 是空格分隔的单字符串（如 reader writer deploy），无法直接用针对数组的 Contains，此时 SplitContains(\scope`, ` `, `writer`)` 就能精确表达“scope 中必须含 writer”。

4.2 布尔组合操作符

所有函数都可以用布尔操作符组合成更复杂的策略：

操作符	说明	示例
&&	仅当两侧都为真时返回真	Equals(\grp`, `admin`) && Equals(`active`, `true`)`
||	两侧任一为真即返回真	Equals(\grp`, `admin`) || Equals(`active`, `true`)`
!	逻辑取反	!Equals(\grp`, `testers`)`

4.3 统一求值示例

文档给出了一个贯穿所有示例的声明数据，本文中所有函数/操作符示例都在如下结构上返回 true：

{
  "active": true,
  "grp": "admin",
  "scope": "reader writer deploy",
  "referrer": "http://example.com/foo/bar",
  "areas": [
    "office",
    "home"
  ]
}

对照验证：Equals(\grp`, `admin`)命中grp=admin；Prefix(`referrer`, `http://example.com`) 命中 referrer 前缀；SplitContains(`scope`, ` `, `writer`) 拆分后命中 writer；Contains(`areas`, `home`)与OneOf(`areas`, `office`, `lab`)` 命中数组元素。

4.4 嵌套 Claims 与键名转义

声明可以是嵌套 JSON 对象，用 . 连接各级键即可取值。文档中的例子如下：

user.name

{
  "active": true,
  "grp": "admin",
  "scope": "reader writer deploy",
  "referrer": "http://example.com/foo/bar",
  "areas": [
    "office",
    "home"
  ],
  "user": {
    "name": "John Snow",
    "status": "undead"
  }
}

John Snow

即 user.name 会解析出嵌套对象里的 "John Snow"。两条取值转义规则同样需要留意：

• 键名本身含 . 时：点号可用 \. 转义，避免被当成层级分隔符；
• 键名本身含 \ 时：需要写成双反斜杠 \\。

从表达式语言的角度看，这种“以反引号包裹参数、用 &&、||、! 组合谓词”的 DSL，与 Traefik 核心路由规则引擎同源：本项目 pkg/rules/parser.go 中 NewParser 基于 github.com/vulcand/predicate 构造解析器，注册 AND、OR、NOT 三种操作符并把函数（即 matcher）按原始大小写、全小写、全大写与 Title 四种形态归一化注册。阅读这段源码有助于理解此类规则表达式为什么支持大小写不敏感与自由组合——claims 表达式采用的正是同一类求值风格。

五、clientConfig：与授权服务器的连接配置

clientConfig 定义 API Gateway 连接第三方软件（如 Identity Provider）所需的全部参数，除前文已列出的 URL、请求头、tokenTypeHint、超时与重试外，重点是 TLS 相关配置。

5.1 用 Kubernetes Secret 托管证书

tls.ca、tls.cert、tls.key 三个字段有两种取值方式：

1. 直接内联 PEM 编码内容；
2. 通过 URN 引用与 Middleware 同命名空间下的 Kubernetes Secret，URN 格式为：

urn:k8s:secret:[name]:[valueKey]

即在 Middleware 中引用名为 tls 的 Secret 的 ca、cert、key 三个键：

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      clientConfig:
        tls:
          ca: "urn:k8s:secret:tls:ca"
          cert: "urn:k8s:secret:tls:cert"
          key: "urn:k8s:secret:tls:key"
          insecureSkipVerify: true

apiVersion: v1
kind: Secret
metadata:
  name: tls
stringData:
  ca: |-
    -----BEGIN CERTIFICATE-----
    MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNV
    BAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl
    Y29kaW5nIG1lPyAgVGhpcyBpcyBvbmx5IGEgdGVzdCEhITERMA8GA1UEBwwISGFt
    aWx0b24xETAPBgNVBAgMCFBlbWJyb2tlMQswCQYDVQQGEwJCTTEPMA0GCSqGSIb3
    DQEJARYAMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJ9WRanG/fUvcfKiGl
    EL4aRLjGt537mZ28UU9/3eiJeJznNSOuNLnF+hmabAu7H0LT4K7EdqfF+XUZW/2j
    RKRYcvOUDGF9A7OjW7UfKk1In3+6QDCi7X34RE161jqoaJjrm/T18TOKcgkkhRzE
    apQnIDm0Ea/HVzX/PiSOGuertwIDAQABMAsGCSqGSIb3DQEBBQOBgQBzMJdAV4QP
    Awel8LzGx5uMOshezF/KfP67wJ93UW+N7zXY6AwPgoLj4Kjw+WtU684JL8Dtr9FX
    ozakE+8p06BpxegR4BR3FMHf6p+0jQxUEAkAyb/mVgm66TyghDGC6/YkiKoZptXQ
    98TwDIK/39WEB/V607As+KoYazQG8drorw==
    -----END CERTIFICATE-----
  cert: |-
    -----BEGIN CERTIFICATE-----
    MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNV
    BAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl
    Y29kaW5nIG1lPyAgVGhpcyBpcyBvbmx5IGEgdGVzdCEhITERMA8GA1UEBwwISGFt
    aWx0b24xETAPBgNVBAgMCFBlbWJyb2tlMQswCQYDVQQGEwJCTTEPMA0GCSqGSIb3
    DQEJARYAMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJ9WRanG/fUvcfKiGl
    EL4aRLjGt537mZ28UU9/3eiJeJznNSOuNLnF+hmabAu7H0LT4K7EdqfF+XUZW/2j
    RKRYcvOUDGF9A7OjW7UfKk1In3+6QDCi7X34RE161jqoaJjrm/T18TOKcgkkhRzE
    apQnIDm0Ea/HVzX/PiSOGuertwIDAQABMAsGCSqGSIb3DQEBBQOBgQBzMJdAV4QP
    Awel8LzGx5uMOshezF/KfP67wJ93UW+N7zXY6AwPgoLj4Kjw+WtU684JL8Dtr9FX
    ozakE+8p06BpxegR4BR3FMHf6p+0jQxUEAkAyb/mVgm66TyghDGC6/YkiKoZptXQ
    98TwDIK/39WEB/V607As+KoYazQG8drorw==
    -----END CERTIFICATE-----
  key: |-
    -----BEGIN EC PRIVATE KEY-----
    MHcCAQEEIC8CsJ/B115S+JtR1/l3ZQwKA3XdXt9zLqusF1VXc/KloAoGCCqGSM49
    AwEHoUQDQgAEpwUmRIZHFt8CdDHYm1ikScCScd2q6QVYXxJu+G3fQZ78ScGtN7fu
    KXMnQqVjXVRAr8qUY8yipVKuMCepnPXScQ==
    -----END EC PRIVATE KEY-----

该 Secret 使用了 stringData 直接存放 PEM 文本，insecureSkipVerify 示例中被置为 true——文档明确提示这“对测试有用，但强烈不建议生产使用”。生产中应让授权服务器使用受信任 CA 签发的证书，保持 insecureSkipVerify: false（默认值），并把私有 CA 的证书包通过 tls.ca 注入信任链。

5.2 与 JWT 中间件的配置一致性

值得注意的是，这套 clientConfig（url/headers/tokenTypeHint/tls/timeout/maxRetries）与仓库内 JWT 中间件文档、OAuth 2.0 Client Credentials 中间件文档 中的 clientConfig、forwardHeaders、claims、usernameClaim 等字段在命名与语义上高度一致（JWT 版本中对应的是 jwksFile/jwksUrl 与验证签名等密钥配置）。这意味着这三类“连接授权服务器进行令牌校验”的 Hub 中间件共享同一套连接、转发与声明校验的设计模型，掌握其中一种后迁移到其它认证中间件的学习成本很低。

六、请求侧行为：令牌来源与放行后处理

6.1 tokenSource：从哪取令牌

支持三种来源，至少配置其一，也可以组合：

• header：从指定请求头取值。当该请求头是 Authorization 时，配合 headerAuthScheme 使用——header: Authorization + headerAuthScheme: Bearer 会剥离 Bearer 前缀后取剩余部分，即标准 Authorization: Bearer <token> 形态；
• query：从指定查询参数取值，适合无法自定义请求头的场景（如文件下载直链）；
• cookie：从指定 Cookie 取值，适合浏览器端传递。

6.2 forwardAuthorization：令牌是否继续向后传

校验通过后，原始令牌是否仍被转发给后端取决于 forwardAuthorization：

• 默认 false：请求经过校验后由网关剥离 Authorization 头再转发。如果后端业务不需要令牌、且不希望令牌被继续传播到内部服务，保持默认即可降低令牌在集群内部扩散的风险；
• true：保留并转发 Authorization 头。当后端需要自行解析令牌、或需要把令牌透传给下游第三方 API 时启用。

6.3 forwardHeaders：声明转请求头

forwardHeaders 是一个映射（map），键是写给后端的新请求头名，值是从内省响应 claims 中取值的键：

forwardHeaders:
  Group: grp
  Expires-At: exp

上例中后端会收到 Group: admin、Expires-At: <exp 值>。文档对缺失声明的行为有明确说明：在 JWT 中找不到对应 claim 时，转发头会被置为空值，因此前端代码应容忍空头的存在。forwardHeaders 是“网关即身份边界”模式的核心部件——业务服务不再需要自行对接 IdP，只需信任网关注入的头即可获得用户身份/属性。

6.4 usernameClaim：访问日志中的用户标识

usernameClaim 指定一个 claim 键，中间件会用其值填充访问日志中的 clientusername 字段。这使网关的访问日志无需解析整段令牌即可直接关联到具体用户，便于审计、限流与排障时按用户维度检索。同样的字段语义也出现在 JWT 中间件文档 中，属于该认证中间件家族的通用约定。

七、中间件的编排位置与适用边界

Traefik 的中间件体系允许将多个中间件挂载在两层：router 级（对命中路由规则的所有请求生效）与 service 级（对该服务处理的请求生效），两者都配置时 router 级先执行。本中间件作为认证类中间件，通常挂载在 router 级，让受保护路由的所有入站请求先过令牌校验，再进入转发与业务逻辑；如需对不同后端差异化放行，也可下沉到 service 级。更完整的编排说明可参考 HTTP 中间件总览。

在适用边界上，文档自洽地划出了一条分界线：

• 本文的 Token Introspection 面向“网关无法本地解析/验证令牌（尤其是不透明令牌），必须实时问询 IdP”的场景，代价是每次请求多一次到授权服务器的 RTT；
• 若令牌本身是 JWT 且你的 IdP 提供 JWKS 端点，可优先评估仓库内的 JWT 中间件——它直接在网关侧验签，无需逐请求回调 IdP；
• 若需要网关代为完成 OAuth 2.0 Client Credentials 授权码换取（机器对机器场景），可参考 OAuth 2.0 Client Credentials 中间件；
• 对于希望在开源 Traefik 中把认证委托给自建认证服务的场景，仓库内置的 ForwardAuth 及其实现 pkg/middlewares/auth/forward.go 是原生提供、可直接使用的对照方案。

八、上手步骤建议

综合文档内容，落地该中间件的最小步骤如下（在 Traefik Hub API Gateway 环境中）：

1. 确认 IdP 的 introspection 端点与鉴权方式：拿到完整的 URL（含 scheme 与 path）、client_id/client_secret（用于 Basic 认证）或自定义的认证请求头、以及是否支持 token_type_hint；
2. 编写 Secret（若需 TLS 或不想在 Middleware 明文存放密钥）：把 CA/客户端证书/私钥放入与 Middleware 同命名空间的 Secret，并用 urn:k8s:secret:[name]:[valueKey] 引用；也可选择直接内联 PEM；
3. 编写 Middleware CRD：按第二节示例补齐 tokenSource、clientConfig.url 与必要的 clientConfig.headers；先不加 claims 验证连通性，再逐步加上声明校验与转发头；
4. 挂载到路由：在对应 IngressRoute/HTTP 路由上引用该 Middleware，配置 forwardAuthorization 决定令牌是否透传后端；
5. 验证与调优：用有效/过期/错误 scope 的令牌分别验证放行与拒绝行为，核对访问日志中的 clientusername，并结合 IdP 实际响应时间评估是否需要调整 timeoutSeconds（默认 5）与 maxRetries（默认 3）。

九、相关参考文档

• 本文主体： oauth2-token-introspection.md（含 RFC 7662 的权威出处链接）
• JWT 认证中间件（同族 clientConfig/claims/forwardHeaders 语义，JWKS 本地验签方案）
• OAuth 2.0 Client Credentials 认证中间件（机器对机器令牌换取方案）
• HTTP 中间件总览（中间件挂载层级与组合规则）
• Traefik Proxy 与 Hub 能力对比（本中间件所属产品定位）
• pkg/rules/parser.go（基于 predicate 的表达式解析实现，可对照理解 claims 表达式的语法根基）