<span class="nav-link-with-icon">Client Credentials <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 使用 RFC 6749 中描述的 OAuth 2.0 客户端凭据流程保护路由。可以使用外部 KV 存储缓存访问令牌。

OAuth 客户端凭据认证中间件支持使用 Redis（或 Sentinel）作为持久化 KV 存储，在授权访问令牌有效期间存储它们。这可以降低延迟，并减少对授权服务器的调用次数。

配置示例¶

OAuth 客户端凭据中间件

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      url: https://tenant.auth0.com/oauth/token
      clientID: urn:k8s:my-secret:my-secret:clientID
      clientSecret: urn:k8s:my-secret:my-secret:clientSecret
      audience: https://api.example.com
      forwardHeaders:
        Group: grp
        Expires-At: exp
      claims: Equals(`grp`, `admin`)

Kubernetes Secret

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: my-secret
stringData:
  clientID: my-oauth-client-name
  clientSecret: mypasswd

配置选项¶

字段	说明	默认值	必填
`audience`	定义在授权服务器中配置的受众。受众值是所访问资源的基础地址，例如：https://api.example.com。	""	是
`claims`	定义为授权请求而需要验证的声明。 `claims` 选项仅可用于 JWT 格式的令牌。（更多信息见此处）	""	否
`clientConfig.tls.ca`	PEM 编码的证书包，或引用包含此证书包的 Secret 的 URN；该证书包用于与授权服务器建立 TLS 连接。（更多信息见此处）	""	否
`clientConfig.tls.cert`	PEM 编码的证书，或引用包含此证书的 Secret 的 URN；该证书用于与 Vault 服务器建立 TLS 连接。（更多信息见此处）	""	否
`clientConfig.tls.key`	PEM 编码的密钥，或引用包含此密钥的 Secret 的 URN；该密钥用于与 Vault 服务器建立 TLS 连接。（更多信息见此处）	""	否
`clientConfig.tls.insecureSkipVerify`	与授权服务器通信时禁用 TLS 证书验证。可用于测试，但强烈不建议在生产环境使用。（更多信息见此处）	false	否
`clientConfig.timeoutSeconds`	定义向授权服务器发出请求后，放弃等待之前的时长。	5	否
`clientConfig.maxRetries`	定义向授权服务器发送请求失败时的重试次数。	3	否
`clientID`	定义 OpenID Connect 提供商中某个账户的唯一客户端标识符；设置 `clientSecret` 时必须设置。更多信息见此处。	""	是
`clientSecret`	定义 OpenID Connect 提供商中某个账户的唯一客户端密钥；设置 `clientID` 时必须设置。更多信息见此处。	""	是
`forwardHeaders`	定义要添加到请求中的 HTTP 头，并使用从授权服务器返回的访问令牌声明中提取的值填充。如果 JWT 中找不到要转发的声明，相应头的值为空。 `forwardHeaders` 选项仅可用于 JWT 格式的令牌。	[]	否
`store.keyPrefix`	定义用于存储会话的条目的键前缀。	""	否
`store.secret`	定义将访问令牌存储到 Redis 时使用的加密密钥。长度必须为 16、24 或 32 个字符。配置 `store` 时必填。	""	是（配置 store 时）
`store.redis.endpoints`	要连接的 Redis 实例端点（例如 `redis.traefik-hub.svc.cluster.local:6379`）。	""	是
`store.redis.username`	Traefik Hub 连接 Redis 时使用的用户名。	""	否
`store.redis.password`	Traefik Hub 连接 Redis 时使用的 password。	""	否
`store.redis.database`	Traefik Hub 用于存储信息的数据库（默认值：`0`）。	0	否
`store.redis.cluster`	启用 Redis Cluster 模式。设置为 `{}` 时启用；省略时禁用。	-	否
`store.redis.tls.ca`	自定义 CA 证书包。	""	否
`store.redis.tls.cert`	TLS 证书。	""	否
`store.redis.tls.key`	TLS。	""	否
`store.redis.tls.insecureSkipVerify`	允许跳过 TLS 验证。	false	否
`store.redis.sentinel.masterSet`	用于主节点选择的主节点集合名称。使用 Sentinel 时必填。	""	是（使用 Sentinel 时）
`store.redis.sentinel.username`	Sentinel 认证使用的用户名（可以与 `username` 不同）。	""	否
`store.redis.sentinel.password`	Sentinel 认证使用的密码（可以与 `password` 不同）。	""	否
`url`	定义授权服务器 URL（例如：`https://tenant.auth0.com/oauth/token`）。	""	是
`usernameClaim`	定义需要求值的声明，以填充访问日志中的 `clientusername`。 `usernameClaim` 选项仅可用于 JWT 格式的令牌。	""	否

在 Kubernetes Secret 中存储机密值¶

可以引用与 Middleware 位于同一命名空间中的 Kubernetes Secret。 Kubernetes Secret 的引用采用 URN 格式：

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

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-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      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-----

store.redis Redis 存储¶

Redis 服务器的连接参数配置在 Middleware 部署中。

支持以下 Redis 模式：

单实例模式
Redis Cluster 集群模式
Redis Sentinel 哨兵模式

提示

如果使用 Redis 单实例模式或 Redis Sentinel，可以配置 database 字段。如果使用 Redis Cluster，此值不会生效（仅可使用数据库 0）。

此时将显示一条警告，并忽略该值。

更多 Redis 信息，建议参阅 Redis 官方文档。

在生产环境使用 Traefik OSS？

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

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

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

配置示例¶

配置选项¶

在 Kubernetes Secret 中存储机密值¶

claims 声明¶

语法¶

嵌套声明¶

clientConfig 客户端配置¶

clientConfig.tls TLS 配置¶

在 Kubernetes Secret 中存储机密值¶

store.redis Redis 存储¶

`clientConfig.tls` TLS 配置¶