<span class="nav-link-with-icon">Token Introspection <img src="https://doc.traefik.io/traefik-hub/img/ps-traefik-hub-logo-light.svg" class="menu-icon" alt="Traefik Hub API Gateway"></span>

Traefik Hub 功能

此中间件仅在 Traefik Hub 中提供。了解更多 Traefik Hub 高级功能。

OAuth 2.0 令牌内省允许 Traefik Hub 从支持令牌内省扩展的 OAuth 2.0 服务器检索访问令牌的元数据。

可以使用这些元数据限制对应用的访问。更多信息参阅 RFC。

配置示例¶

OAuth 令牌内省中间件

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`)

配置选项¶

字段	说明	默认值	必填
`claims`	定义为授权请求而需要验证的声明。 `claims` 选项仅可用于 JWT 格式的令牌。（更多信息见此处）	""	否
`clientConfig.url`	定义内省端点的 URL，必须包含协议方案和路径。	""	是
`clientConfig.headers`	定义每次内省请求都发送的头。值可以是普通字符串，也可以是有效的 Go 模板。目前，模板可以访问一个 `Request` 类型的变量，对应正在内省的请求。	""	否
`clientConfig.tokenTypeHint`	定义正在内省的令牌类型，作为提示发送给内省服务器。更多详情参阅官方文档。	""	否
`clientConfig.tls.ca`	PEM 编码的证书包，或引用包含此证书包的 Secret 的 URN；该证书包用于与授权服务器建立 TLS 连接。（更多信息见此处）	""	否
`clientConfig.tls.cert`	PEM 编码的证书，或引用包含此证书的 Secret 的 URN；该证书用于与授权服务器建立 TLS 连接。（更多信息见此处）	""	否
`clientConfig.tls.key`	PEM 编码的密钥，或引用包含此密钥的 Secret 的 URN；该密钥用于与授权服务器建立 TLS 连接。（更多信息见此处）	""	否
`clientConfig.tls.insecureSkipVerify`	与授权服务器通信时禁用 TLS 证书验证。可用于测试，但强烈不建议在生产环境使用。（更多信息见此处）	false	否
`clientConfig.timeoutSeconds`	定义向授权服务器发出请求后，放弃等待之前的时长。	5	否
`clientConfig.maxRetries`	定义向授权服务器发送请求失败时的重试次数。	3	否
`forwardAuthorization`	定义请求通过中间件批准后，是转发还是移除其中的认证头。	false	否
`forwardHeaders`	定义要添加到请求中的 HTTP 头，并使用从授权服务器返回的访问令牌声明中提取的值填充。如果 JWT 中找不到要转发的声明，相应头的值为空。 `forwardHeaders` 选项仅可用于 JWT 格式的令牌。	[]	否
`tokenSource.header`	定义包含客户端所发送密钥的请求头名称。必须至少设置一个 `tokenSource` 选项。	""	否
`tokenSource.headerAuthScheme`	使用 `Authorization` 作为请求头名称时，定义认证方案。参阅 `Authorization` 请求头文档。必须至少设置一个 `tokenSource` 选项。	""	否
`tokenSource.query`	定义包含客户端所发送密钥的查询参数名称。必须至少设置一个 `tokenSource` 选项。	""	否
`tokenSource.cookie`	定义包含客户端所发送密钥的 Cookie 名称。必须至少设置一个 `tokenSource` 选项。	""	否
`usernameClaim`	定义需要求值的声明，以填充访问日志中的 `clientusername`。 `usernameClaim` 选项仅可用于 JWT 格式的令牌。	""	否

claims 声明¶

语法¶

claims 支持以下函数：

函数	说明	示例
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`)

所有函数都可以通过布尔运算符连接。支持以下运算符：

运算符	说明	示例
&&	比较两个函数，仅当二者都求值为 true 时返回 true。	Equals(`grp`, `admin`) && Equals(`active`, `true`)
\|\|	比较两个函数，只要任意一个求值为 true 就返回 true。	Equals(`grp`, `admin`) \|\| Equals(`active`, `true`)
!	函数为 true 时返回 false，否则返回 true。	!Equals(`grp`, `testers`)

对于以下数据结构，所有示例都会返回 true：

JSON

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

嵌套声明¶

在键之间使用 . 可以支持嵌套声明。例如：

键

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

处理包含 '.' 的键

如果 key 包含点号，可以使用 \. 转义。

处理包含 '\' 的键

如果 key 包含 \，则需要写成两个：\\。

clientConfig 客户端配置¶

定义 API 网关连接身份提供商等第三方软件时使用的配置。

`clientConfig.tls` TLS 配置¶

在 Kubernetes Secret 中存储机密值¶

配置 tls.ca、tls.cert、tls.key 时，可以引用与 Middleware 位于同一命名空间中的 Kubernetes Secret。 Kubernetes Secret 的引用采用 URN 格式：

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

JWT 中间件

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

Kubernetes TLS Secret

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-----

在生产环境使用 Traefik OSS？

如果你在工作中使用 Traefik，可以考虑为 Traefik OSS 增加企业级 API 网关能力或商业支持。

为 Traefik OSS 增加 API 网关能力快捷且平滑，无需推倒重来，现有配置也会完整保留。请通过这个简短视频了解实际效果。

<span class="nav-link-with-icon">Token Introspection <img src="https://doc.traefik.io/traefik-hub/img/ps-traefik-hub-logo-light.svg" class="menu-icon" alt="Traefik Hub API Gateway"></span>

配置示例¶

配置选项¶

claims 声明¶

语法¶

嵌套声明¶

clientConfig 客户端配置¶

clientConfig.tls TLS 配置¶

在 Kubernetes Secret 中存储机密值¶

`clientConfig.tls` TLS 配置¶