OAuth 2.0 Client Credentials Authentication

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

The OAuth Client Credentials Authentication middleware allows using Redis (or Sentinel) as persistent KV store to authorization access tokens while they are valid. This reduces latency and the number of calls made to the authorization server.

---

Configuration Options

url

Field	Description	Default	Required
url	Defines the authorization server URL (for example: https://tenant.auth0.com/oauth/token).	""	Yes

Defining the authorization server URL

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      url: https://tenant.auth0.com/oauth/token

clientID and clientSecret

Field	Description	Default	Required
clientID	Defines the unique client identifier for an account on the authorization server, must be set when the clientSecret option is set.	""	No
clientSecret	Defines the unique client secret for an account on the authorization server, must be set when the clientID option is set.	""	No

Storing secret values in Kubernetes secrets

When configuring the clientID and the clientSecret, it is possible to reference Kubernetes secrets defined in the same namespace as the Middleware. The reference to a Kubernetes secret takes the form of a URN:

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

Middleware configuration

Referencing the Kubernetes secret

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      url: "https://tenant.auth0.com/oauth/token"
      clientID: urn:k8s:secret:my-secret:clientId
      clientSecret: urn:k8s:secret:my-secret:clientSecret

Kubernetes Secret

Creating the Kubernetes secret

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

audience

Field	Description	Default	Required
audience	Defines the audience configured in your authorization server. The audience value is the base address of the resource being accessed, for example: https://api.example.com.	""	Yes

Defining the audience

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

claims

Field	Description	Default	Required
claims	Defines the claims to validate in order to authorize the request.	""	No

note

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

Validating that clients are in the admin group

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

Syntax

The following functions are supported in claims:

Function	Description	Example
Equals	Validates 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:

JSON

{
  "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 \\.

forwardHeaders

Field	Description	Default	Required
forwardHeaders	Defines the HTTP headers to add to requests and populates them with values extracted from the access token claims returned by the authorization server.	[]	No

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

Forwarding the grp and exp claims as HTTP headers

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

usernameClaim

Field	Description	Default	Required
usernameClaim	Defines the claim that will be evaluated to populate the clientusername in the access logs.	""	No

note

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

Defining the claim used to log the clientusername

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      usernameClaim: userId

clientConfig

Defines the configuration used to connect the API Gateway to a Third Party Software such as an Identity Provider.

clientConfig.tls

The table below lists the configuration options in Traefik Hub to define a TLS connection.

Value	Description	Required
clientConfig.tls.ca	PEM-encoded certificate bundle or a URN referencing a secret containing the certificate bundle used to establish a TLS connection with the authorization server	No
clientConfig.tls.cert	PEM-encoded certificate or a URN referencing a secret containing the certificate used to establish a TLS connection with the Vault server	No
clientConfig.tls.key	PEM-encoded key or a URN referencing a secret containing the key used to establish a TLS connection with the Vault server.	No
clientConfig.tls.insecureSkipVerify	Disables TLS certificate verification when communicating with the authorization server. Useful for testing purposes but strongly discouraged for production.	No

Storing secret values in Kubernetes secrets

When configuring the tls.ca, tls.cert, tls.key, it is possible to reference Kubernetes secrets defined in the same namespace as the Middleware.
The reference to a Kubernetes secret takes the form of a URN:

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

Middleware configuration

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

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

clientConfig.timeoutSeconds

Field	Description	Default	Required
clientConfig.timeoutSeconds	Defines the time before giving up requests to the authorization server.	5	No

Increasing the timeout

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      clientConfig:
        timeoutSeconds: 15

clientConfig.maxRetries

Field	Description	Default	Required
clientConfig.maxRetries	Defines the number of retries for requests to authorization server that fail.	3	No

Increasing the maximum number of retries

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      clientConfig:
        maxRetries: 5

store

store.keyPrefix

Field	Description	Default	Required
store.keyPrefix	Defines the prefix of the key for the entries that store the sessions.	""	No

Defining the key prefix

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      store:
        keyPrefix: prefix

store.secret

Field	Description	Default	Required
store.secret	The encryption key used to secure token information in the store, it must be 16, 24 or 32 characters long.	""	No

Storing secret values in Kubernetes secrets

When configuring the clientID and the clientSecret, it is possible to reference Kubernetes secrets defined in the same namespace as the Middleware. The reference to a Kubernetes secret takes the form of a URN:

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

Middleware configuration

Defining the encryption key

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-client-creds
spec:
  plugin:
    oAuthClientCredentials:
      store:
        secret: "urn:k8s:secret:my-store-secret:secret"

Kubernetes Secret

Creating the Kubernetes secret

apiVersion: v1
kind: Secret
metadata:
  name: my-store-secret
stringData:
  secret: mysupersecret123456

store.redis

Connection parameters to your Redis server are attached to your Middleware deployment.

The following Redis modes are supported:

• Single instance mode
• Redis Cluster
• Redis Sentinel

info

For more information about Redis, we recommend the official Redis documentation.

The table below lists the configuration options in Traefik Hub to connect to Redis and store middleware information.

Value	Description	Required
redis.endpoints	Endpoints of the Redis instances to connect to (example: redis.traefik-hub.svc.cluster.local:6379)	Yes
redis.username	The username Traefik Hub will use to connect to Redis	No
redis.password	The password Traefik Hub will use to connect to Redis	No
redis.database	The database Traefik Hub will use to sore information (default: 0)	No
redis.cluster	Enable Redis Cluster	No
redis.tls.caBundle	Custom CA bundle	No
redis.tls.cert	TLS certificate	No
redis.tls.key	TLS key	No
redis.tls.insecureSkipVerify	Allow skipping the TLS verification	No
redis.sentinel.masterSet	Name of the set of main nodes to use for main selection. Required when using Sentinel.	No
redis.sentinel.username	Username to use for sentinel authentication (can be different from username)	No
redis.sentinel.password	Password to use for sentinel authentication (can be different from password)	No

info

If you use Redis in single instance mode or Redis Sentinel, you can configure the database field. This value won't be taken into account if you use Redis Cluster (only database 0 is available).

In this case, a warning is displayed, and the value is ignored.

Advanced Configuration Example

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

Middleware configuration

Using custom claims validation and forwarding headers

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

Kubernetes Secret

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