Skip to main content

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

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

Configuration Options​

FieldDescriptionDefaultRequired
audienceDefines 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
claimsDefines the claims to validate in order to authorize the request.
The claims option can only be used with JWT-formatted token. (More information here)		""No
clientConfig.tls.caPEM-encoded certificate bundle or a URN referencing a secret containing the certificate bundle used to establish a TLS connection with the authorization server (More information here)""No
clientConfig.tls.certPEM-encoded certificate or a URN referencing a secret containing the certificate used to establish a TLS connection with the Vault server (More information here)""No
clientConfig.tls.keyPEM-encoded key or a URN referencing a secret containing the key used to establish a TLS connection with the Vault server. (More information here)""No
clientConfig.tls.insecureSkipVerifyDisables TLS certificate verification when communicating with the authorization server.
Useful for testing purposes but strongly discouraged for production. (More information here)		""No
clientConfig.timeoutSecondsDefines the time before giving up requests to the authorization server.5No
clientConfig.maxRetriesDefines the number of retries for requests to authorization server that fail.3No
clientIDDefines the unique client identifier for an account on the OpenID Connect provider, must be set when the clientSecret option is set.
More information here.		""Yes
clientSecretDefines the unique client secret for an account on the OpenID Connect provider, must be set when the clientID option is set.
More information here.		""Yes
forwardHeadersDefines the HTTP headers to add to requests and populates them with values extracted from the access token claims returned by the authorization server.
Claims to be forwarded that are not found in the JWT result in empty headers.
The forwardHeaders option can only be used with JWT-formatted token.		[]No
store.keyPrefixDefines the prefix of the key for the entries that store the sessions.""No
store.redis.endpointsEndpoints of the Redis instances to connect to (example: redis.traefik-hub.svc.cluster.local:6379)""Yes
store.redis.usernameThe username Traefik Hub will use to connect to Redis""No
store.redis.passwordThe password Traefik Hub will use to connect to Redis""No
store.redis.databaseThe database Traefik Hub will use to sore information (default: 0)""No
store.redis.clusterEnable Redis Cluster""No
store.redis.tls.caBundleCustom CA bundle""No
store.redis.tls.certTLS certificate""No
store.redis.tls.keyTLS key""No
store.redis.tls.insecureSkipVerifyAllow skipping the TLS verification""No
store.redis.sentinel.masterSetName of the set of main nodes to use for main selection. Required when using Sentinel.""No
store.redis.sentinel.usernameUsername to use for sentinel authentication (can be different from username)""No
store.redis.sentinel.passwordPassword to use for sentinel authentication (can be different from password)""No
urlDefines the authorization server URL (for example: https://tenant.auth0.com/oauth/token).""Yes
usernameClaimDefines the claim that will be evaluated to populate the clientusername in the access logs.
The usernameClaim option can only be used with JWT-formatted token.		""No

Storing secret values in Kubernetes secrets​

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]

claims​

Syntax​

The following functions are supported in claims:

FunctionDescriptionExample
EqualsValidates the equality of the value in key with value.Equals(`grp`, `admin`)
PrefixValidates 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`)
SplitContainsValidates the value in key contains the value once split by the separator.SplitContains(`scope`, ` `, `writer`)
OneOfValidates the key array contains one of the values.OneOf(`areas`, `office`, `lab`)

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

OperandDescriptionExample
&&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 \\.

clientConfig​

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

clientConfig.tls​

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

store.redis​

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

The following Redis modes are supported:

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

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.