OAuth 2.0 Client Credentials¶

The OAuth 2.0 Client Credentials middleware allows Traefik Enterprise to secure routes using the OAuth 2.0 Client Credentials flow as described in the RFC 6749. Access tokens are cached using an external KV store.

Authentication Source¶

Before configuring an OAuth 2.0 Client Credentials middleware, an Authentication Source must be defined in the static configuration.

Below is an example of a minimal Authentication Source that can be added to a static configuration:

YAML

authSources:
  clientCredsSource:
    oAuthClientCredentials:
      url: https://auth.server.com

TOML

[authSources]
  [authSources.clientCredsSource]
    [authSources.clientCredsSource.oAuthClientCredentials]
      url = "https://auth.server.com"

Authentication Source Options¶

`url`¶

Required, Default=""

The url is the URL to the authorization server (e.g.: https://tenant.auth0.com/oauth/token).

YAML

authSources:
  clientCredsSource:
    oAuthClientCredentials:
      url: https://tenant.auth0.com/oauth/token

TOML

[authSources]
  [authSources.clientCredsSource]
    [authSources.clientCredsSource.oAuthClientCredentials]
      url = "https://tenant.auth0.com/oauth/token"

`clientID`¶

Optional

The clientID is the unique client identifier for an account on the authorization server, must be set when the clientSecret option is set.

YAML

authSources:
  clientCredsSource:
    oAuthClientCredentials:
      clientID: client-id

TOML

[authSources]
  [authSources.clientCredsSource]
    [authSources.clientCredsSource.oAuthClientCredentials]
      clientID = "client-id"

`clientSecret`¶

Optional

The clientSecret is the unique client secret for an account on the authorization server, must be set when the clientID option is set.

YAML

authSources:
  clientCredsSource:
    oAuthClientCredentials:
      clientSecret: client-secret

TOML

[authSources]
  [authSources.clientCredsSource]
    [authSources.clientCredsSource.oAuthClientCredentials]
      clientSecret = "client-secret"

`tls`¶

Optional

Defines the TLS configuration used for the secure connection to the authorization server.

`tls.caBundle`¶

Optional, Default=""

An optional caBundle containing a PEM-encoded certificate bundle or a path to a file containing the certificate bundle used to establish a TLS connection with the authorization server.

Using a File

Note that TraefikEE does not watch for file changes. If caBundle is set to a file path, its content will be read once when the middleware is initialized.

File (YAML) using content

authSources:
  clientCredsSource:
    oAuthClientCredentials:
      tls:
        caBundle: |-
          -----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-----

File (YAML) using file path

authSources:
  clientCredsSource:
    oAuthClientCredentials:
      tls:
        caBundle: /etc/tls/ca-bundle.pem

File (TOML)

[authSources]
  [authSources.clientCredsSource]
    [authSources.clientCredsSource.oAuthClientCredentials.tls]
      caBundle = """
-----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-----
"""

File (TOML) using file path

[authSources]
  [authSources.clientCredsSource]
    [authSources.clientCredsSource.oAuthClientCredentials.tls]
      caBundle = "/etc/tls/ca-bundle.pem"

`tls.insecureSkipVerify`¶

Optional, Default=false

Disables TLS certificate verification when communicating with the authorization server. Useful for testing purposes but strongly discouraged for production.

File (YAML)

authSources:
  clientCredsSource:
    oAuthClientCredentials:
      tls:
        insecureSkipVerify: true

File (TOML)

[authSources]
  [authSources.clientCredsSource]
    [authSources.clientCredsSource.oAuthClientCredentials.tls]
      insecureSkipVerify = true

`timeout`¶

Optional, Default="5s"

This option controls the time before giving up requests to the authorization server.

File (YAML)

authSources:
  clientCredsSource:
    oAuthClientCredentials:
      timeout: 15s

File (TOML)

[authSources]
  [authSources.clientCredsSource.oAuthClientCredentials]
    timeout = "15s"

`maxRetries`¶

Optional, Default=3

The number of retries for requests to authorization server that fail.

File (YAML)

authSources:
  clientCredsSource:
    oAuthClientCredentials:
      maxRetries: 5

File (TOML)

[authSources]
  [authSources.clientCredsSource.oAuthClientCredentials]
    maxRetries = 5

Token Cache¶

The OAuth Client Credentials Authentication middleware uses a persistent KV store to authorization access tokens while they are valid. This reduces latency and the number of calls made to the authorization server.

Below is an example of a reference of all the possible options when configuring a consul KV storage in the static configuration.

Info

The options are all the same for the three other storage types (etcd, zookeeper, and redis), except for namespace, and token.

YAML

stores:

  consulStore:
    # the value has to match one of the possible
    # kv store types (consul, etcd, zookeeper, and redis).
    consul:
      keyPrefix: traefikee
      endpoints:
        - 'localhost:8500'

      username: foo
      password: bar
      token: baz
      namespace: production

      tls:
        caBundle: path/to/ca.crt
        insecureSkipVerify: false

TOML

[stores]

  # the value has to match one of the possible
  # kv store types (consul, etcd, zookeeper, and redis).
  [stores.consulStore.consul]
    keyPrefix = "traefikee"
    endpoints = ["localhost:8500"]
    username = "foo"
    password = "bar"
    token = "baz"
    namespace = "production"

    [stores.consulStore.consul.tls]
      caBundle = "path/to/ca.crt"
      insecureSkipVerify = false

Store Options¶

Warning

In the examples below, storeType should be replaced by one of the possible store types: etcd, zookeeper, redis, consul.

`endpoints`¶

Required, Default=""

Defines how to access the KV Store.

File (YAML)

stores:
  foo:
    storeType:
      endpoints:
        - "127.0.0.1:8500"

File (TOML)

[stores]
  [stores.foo.storeType]
    endpoints = ["127.0.0.1:8500"]

`keyPrefix`¶

Optional, Default=""

KeyPrefix optionally configures the prefix of the key for the entries that store the sessions.

File (YAML)

stores:
  foo:
    storeType:
      keyPrefix: "traefikee"

File (TOML)

[stores]
  [stores.foo.storeType]
    keyPrefix = traefikee

`username`¶

Optional, Default=""

Defines a username to connect to the KV store.

File (YAML)

stores:
  foo:
    storeType:
      username: "foo"
      password: "bar"

File (TOML)

[stores]
  [stores.foo.storeType]
    username = foo
    password = bar

`password`¶

Optional, Default=""

Defines a password to connect to the KV store.

File (YAML)

stores:
  foo:
    storeType:
      username: "foo"
      password: "bar"

File (TOML)

[stores]
  [stores.foo.storeType]
    username: foo
    password: bar

`tls`¶

Optional

Defines the TLS configuration used for the secure connection to the KV store.

A (possibly empty) TLS section is necessary to connect to a TLS endpoint.

`tls.caBundle`¶

Optional, Default=""

An optional caBundle containing a PEM-encoded certificate bundle or a path to a file containing the certificate bundle used to establish a TLS connection with the KV store.

Using a File

Note that TraefikEE does not watch for file changes. If caBundle is set to a file path, its content will be read once when the KV store client is initialized.

File (YAML) using content

stores:
  foo:
    storeType:
      tls:
        caBundle: |-
          -----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-----

File (YAML) using file path

stores:
  foo:
    storeType:
      tls:
        caBundle: /etc/tls/ca-bundle.pem

File (TOML)

[stores]
  [stores.foo]
    [stores.foo.storeType.tls]
      caBundle = """
-----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-----
"""

File (TOML) using file path

[stores]
  [stores.foo]
    [stores.foo.storeType.tls]
      caBundle = "/etc/tls/ca-bundle.pem"

`tls.insecureSkipVerify`¶

Optional, Default=false

If insecureSkipVerify is true, the TLS connection to the KV store accepts any certificate presented by the server regardless of the hostnames it covers.

File (YAML)

stores:
  foo:
    storeType:
      tls:
        insecureSkipVerify: true

File (TOML)

[stores]
  [stores.foo.storeType.tls]
    insecureSkipVerify = true

Consul Specific Options¶

`namespace`¶

Optional, Default=""

The namespace option defines the namespace to query.

Warning

The namespace option only works with Consul Enterprise, which provides the Namespaces feature.

File (YAML)

stores:
  foo:
    storeType:
      namespace: production

File (TOML)

[stores]
  [stores.foo.storeType]
    namespace = "production"

`token`¶

Optional, Default=""

Defines a token with which to connect to Consul.

File (YAML)

stores:
  foo:
    storeType:
      token: secret

File (TOML)

[stores]
  [stores.foo.storeType]
    token = "secret"

Redis Specific Options¶

`db`¶

Optional, Default=0

Defines the database to be selected after connecting to the Redis.

File (YAML)

stores:
  foo:
    storeType:
      db: 0

File (TOML)

[stores]
  [stores.foo.storeType]
    db = 0

`sentinel`¶

Optional

Defines the Sentinel configuration used to interact with Redis Sentinel.

`sentinel.masterName`¶

Required

masterName is the name of the Sentinel master.

File (YAML)

stores:
  foo:
    storeType:
      sentinel:
        masterName: my-master

File (TOML)

[stores]
  [stores.foo.storeType.sentinel]
    masterName = "my-master"

`sentinel.username`¶

Optional

username is the username for Sentinel authentication.

File (YAML)

stores:
  foo:
    storeType:
      sentinel:
        username: user

File (TOML)

[stores]
  [stores.foo.storeType.sentinel]
    username = "user"

`sentinel.password`¶

Optional

password is the password for Sentinel authentication.

File (YAML)

stores:
  foo:
    storeType:
      sentinel:
        password: password

File (TOML)

[stores]
  [stores.foo.storeType.sentinel]
    password = "password"

`sentinel.latencyStrategy`¶

Optional, Default=false

latencyStrategy defines whether to route commands to the closest master or replica nodes (mutually exclusive with RandomStrategy and ReplicaStrategy).

File (YAML)

stores:
  foo:
    storeType:
      sentinel:
        latencyStrategy: true

File (TOML)

[stores]
  [stores.foo.storeType.sentinel]
    latencyStrategy = true

`sentinel.randomStrategy`¶

Optional, Default=false

randomStrategy defines whether to route commands randomly to master or replica nodes (mutually exclusive with LatencyStrategy and ReplicaStrategy).

File (YAML)

stores:
  foo:
    storeType:
      sentinel:
        randomStrategy: true

File (TOML)

[stores]
  [stores.foo.storeType.sentinel]
    randomStrategy = true

`sentinel.replicaStrategy`¶

Optional, Default=false

replicaStrategy Defines whether to route all commands to replica nodes (mutually exclusive with LatencyStrategy and RandomStrategy).

File (YAML)

stores:
  foo:
    storeType:
      sentinel:
        replicaStrategy: true

File (TOML)

[stores]
  [stores.foo.storeType.sentinel]
    replicaStrategy = true

`sentinel.useDisconnectedReplicas`¶

Optional, Default=false

useDisconnectedReplicas defines whether to use replicas disconnected with master when cannot get connected replicas.

File (YAML)

stores:
  foo:
    storeType:
      sentinel:
        useDisconnectedReplicas: true

File (TOML)

[stores]
  [stores.foo.storeType.sentinel]
    useDisconnectedReplicas = true

OAuth 2.0 Client Credentials Middleware¶

After declaring an Authentication Source in the static configuration of the cluster, OAuth 2.0 Client Credentials middleware can be added to routers in the dynamic configuration.

Middleware Options¶

`source`¶

Required, Default=""

The source option should contain the name of the Authentication Source used by the middleware.

Docker

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.source=clientCredsSource"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      source: clientCredsSource

Consul Catalog

- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.source=clientCredsSource"

Marathon

"labels": {
  "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.source": "clientCredsSource"
}

Rancher

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.source=clientCredsSource"

File (YAML)

http:
  middlewares:
    test-client-creds:
      plugin:
        oAuthClientCredentials:
          source: clientCredsSource

File (TOML)

[http.middlewares]
  [http.middlewares.test-client-creds.plugin.oAuthClientCredentials]
    source = "clientCredsSource"

`store`¶

Required, Default=""

The store option should contain the name of the Store used by the middleware.

Docker

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.store=clientCredsStore"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      store: clientCredsStore

Consul Catalog

- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.store=clientCredsStore"

Marathon

"labels": {
  "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.store": "clientCredsStore"
}

Rancher

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.store=clientCredsStore"

File (YAML)

http:
  middlewares:
    test-client-creds:
      plugin:
        oAuthClientCredentials:
          store: clientCredsStore

File (TOML)

[http.middlewares]
  [http.middlewares.test-client-creds.plugin.oAuthClientCredentials]
    store = "clientCredsStore"

`storeSecret`¶

Optional, Default=""

The encryption key used to secure token information in the store, it must be 16, 24 or 32 characters long. TraefikEE generates one if none is provided.

Docker

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.storeSecret=mysecret12345678"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      storeSecret: "mysecret12345678"

Consul Catalog

- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.storeSecret=mysecret12345678"

Marathon

"labels": {
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.storeSecret": "mysecret12345678"
}

Rancher

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.storeSecret=mysecret12345678"

File (YAML)

http:
  middlewares:
    test-client-creds:
      plugin:
        oAuthClientCredentials:
          storeSecret: "mysecret12345678"

File (TOML)

[http.middlewares]
  [http.middlewares.test-client-creds.plugin.oAuthClientCredentials]
    storeSecret = "mysecret12345678"

`audience`¶

Required, Default=""

The audience option must match the audience configured in your authorization server. The audience value is generally the base address of the resource being accessed, for example: https://api.example.com.

Docker

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.audience=https://api.example.com"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      audience: https://api.example.com

Consul Catalog

- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.audience=https://api.example.com"

Marathon

"labels": {
  "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.audience": "https://api.example.com"
}

Rancher

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.audience=https://api.example.com"

File (YAML)

http:
  middlewares:
    test-client-creds:
      plugin:
        oAuthClientCredentials:
          audience: https://api.example.com

File (TOML)

[http.middlewares]
  [http.middlewares.test-client-creds.plugin.oAuthClientCredentials]
    audience = "https://api.example.com"

`forwardHeaders`¶

Optional, Default=None

The forwardHeaders option sets the HTTP headers to add to requests and populates them with values extracted from the access token claims returned by the authorization server.

Note

Claims to be forwarded that are not found in the JWT result in empty headers.

Note

The forwardHeaders option can only be used with JWT-formatted access token.

Docker

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Expires-At=exp"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      forwardHeaders:
        Group: grp
        Expires-At: exp

Consul Catalog

- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Group=grp"
- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Expires-At=exp"

Marathon

"labels": {
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Group": "grp",
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Expires-At": "exp"
}

Rancher

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Expires-At=exp"

File (YAML)

http:
  middlewares:
    test-client-creds:
      plugin:
        oAuthClientCredentials:
          forwardHeaders:
            Group: grp
            Expires-At: exp

File (TOML)

[http.middlewares]
  [http.middlewares.test-client-creds.plugin.oAuthClientCredentials]
    [http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders]
      Group = "grp"
      Expires-At = "exp"

`username`¶

Optional, Default=""

The username option sets the claim that will be evaluated to populate the clientusername in the accessLog.

Note

The username option can only be used with JWT-formatted access token.

Docker

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.username=userId"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      username: userId

Consul Catalog

- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.username=userId"

Marathon

"labels": {
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.username": "userId"
}

Rancher

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.username=userId"

File (YAML)

http:
  middlewares:
    test-jwt:
      plugin:
        oAuthClientCredentials:
          username: userId

File (TOML)

[http.middlewares]
  [http.middlewares.test-client-creds.plugin.oAuthClientCredentials]
    username = userId

`claims`¶

Optional, Default=""

The claims option sets claims to validate in order to authorize the request.

Note

The claims option can only be used with JWT-formatted access token.

Docker

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.claims=Equals(`grp`, `admin`)"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      claims: Equals(`grp`, `admin`)

Consul Catalog

- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.claims=Equals(`grp`, `admin`)"

Marathon

"labels": {
  "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.claims": "Equals(`grp`, `admin`)"
}

Rancher

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.claims=Equals(`grp`, `admin`)"

File (YAML)

http:
  middlewares:
    test-client-creds:
      plugin:
        oAuthClientCredentials:
          claims: Equals(`grp`, `admin`)

File (TOML)

[http.middlewares]
  [http.middlewares.test-client-creds.plugin.oAuthClientCredentials]
    claims = "Equals(`grp`, `admin`)"

Syntax¶

The following functions are supported in claims:

Function	Description	Example
Equals	Validated the equality of the value in `key` with `value`.	Equals(`grp`, `admin`)
Prefix	Validates the value in `key` has the prefix of `value`.	Prefix(`referrer`, `http://example.com`)
Contains (string)	Validates the value in `key` contains `value`.	Contains(`referrer`, `/foo/`)
Contains (array)	Validates the `key` array contains the `value`.	Contains(`areas`, `home`)
SplitContains	Validates the value in `key` contains the `value` once split by the separator.	SplitContains(`scope`, ` `, `writer`)
OneOf	Validates the `key` array contains one of the `values`.	OneOf(`areas`, `office`, `lab`)

All functions can be joined by boolean operands. The supported operands are:

Operand	Description	Example
&&	Compares two functions and returns true only if both evaluate to true.	Equals(`grp`, `admin`) && Equals(`active`, `true`)
\|\|	Compares two functions and returns true if either evaluate to true.	Equals(`grp`, `admin`) \|\| Equals(`active`, `true`)
!	Returns false if the function is true, otherwise returns true.	!Equals(`grp`, `testers`)

All examples will return true for the following data structure:

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

Nested claims¶

Nested claims are supported by using a . between keys. For example:

Key

user.name

Claims

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

Result

John Snow

Handling keys that contain a '.'

If the key contains a dot, the dot can be escaped using \.

Handling a key that contains a '\'

If the key contains a \, it needs to be doubled \\.

Advanced Configuration Example¶

Below is an advanced configuration example using custom claims validation and forward headers:

Docker

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.source=clientCredsSource"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.store=clientCredsStore"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.audience=https://api.example.com"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Expires-At=exp"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.claims: Equals(`grp`, `admin`)"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      source: clientCredsSource
      store: clientCredsStore
      audience: https://api.example.com
      forwardHeaders:
        Group: grp
        Expires-At: exp
      claims: Equals(`grp`, `admin`)

Consul Catalog

- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.source=clientCredsSource"
- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.store=clientCredsStore"
- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.audience=https://api.example.com"
- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Group=grp"
- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Expires-At=exp"
- "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.claims: Equals(`grp`, `admin`)"

Marathon

"labels": {
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.source": "clientCredsSource",
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.store": "clientCredsStore",
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.audience": "https://api.example.com",
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Group": "grp",
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Expires-At": "exp",
    "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.claims": "Equals(`grp`, `admin`)"
}

Rancher

labels:
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.source=clientCredsSource"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.store=clientCredsStore"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.audience=https://api.example.com"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders.Expires-At=exp"
  - "traefik.http.middlewares.test-client-creds.plugin.oAuthClientCredentials.claims: Equals(`grp`, `admin`)"

File (YAML)

http:
  middlewares:
    test-client-creds:
      plugin:
        oAuthClientCredentials:
          source: clientCredsSource
          store: clientCredsStore
          audience: https://api.example.com
          forwardHeaders:
            Group: grp
            Expires-At: exp
          claims: Equals(`grp`, `admin`)

File (TOML)

[http.middlewares]
  [http.middlewares.test-client-creds.plugin.oAuthClientCredentials]
    source = "clientCredsSource"
    store = "clientCredsStore"
    audience = "https://api.example.com"
    [http.middlewares.test-client-creds.plugin.oAuthClientCredentials.forwardHeaders]
      Group = "grp"
      Expires-At = "exp"
    claims = "Equals(`grp`, `admin`)"

OAuth 2.0 Client Credentials¶

Authentication Source¶

Authentication Source Options¶

url¶

clientID¶

clientSecret¶

tls¶

tls.caBundle¶

tls.insecureSkipVerify¶

timeout¶

maxRetries¶

Token Cache¶

Store Options¶

endpoints¶

keyPrefix¶

username¶

password¶

tls¶

tls.caBundle¶

tls.insecureSkipVerify¶

Consul Specific Options¶

namespace¶

token¶

Redis Specific Options¶

db¶

sentinel¶

sentinel.masterName¶

sentinel.username¶

sentinel.password¶

sentinel.latencyStrategy¶

sentinel.randomStrategy¶

sentinel.replicaStrategy¶

sentinel.useDisconnectedReplicas¶

OAuth 2.0 Client Credentials Middleware¶

Middleware Options¶

source¶

store¶

storeSecret¶

audience¶

forwardHeaders¶

username¶

claims¶

Syntax¶

Nested claims¶

Advanced Configuration Example¶

`url`¶

`clientID`¶

`clientSecret`¶

`tls`¶

`tls.caBundle`¶

`tls.insecureSkipVerify`¶

`timeout`¶

`maxRetries`¶

`endpoints`¶

`keyPrefix`¶

`username`¶

`password`¶

`tls`¶

`tls.caBundle`¶

`tls.insecureSkipVerify`¶

`namespace`¶

`token`¶

`db`¶

`sentinel`¶

`sentinel.masterName`¶

`sentinel.username`¶

`sentinel.password`¶

`sentinel.latencyStrategy`¶

`sentinel.randomStrategy`¶

`sentinel.replicaStrategy`¶

`sentinel.useDisconnectedReplicas`¶

`source`¶

`store`¶

`storeSecret`¶

`audience`¶

`forwardHeaders`¶

`username`¶

`claims`¶