Skip to main content

OAuth 2.0 Token Exchange Authentication

Early Access

This feature is currently in early access.

The OAuth 2.0 Token Exchange middleware exchanges an incoming subject token for a new, downstream-scoped access token before forwarding the request. It supports the RFC 8693 token-exchange grant and the Microsoft Entra ID On-Behalf-Of flow. Exchanged tokens can be cached using an external KV store, so Hub API Gateway does not call the authorization server on every request.

Configuration Example​

RFC 8693 token exchange
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-token-exchange
spec:
  plugin:
    oAuthTokenExchange:
      method: rfc8693
      url: https://tenant.auth0.com/oauth/token
      clientID: urn:k8s:secret:my-secret:clientID
      clientSecret: urn:k8s:secret:my-secret:clientSecret
      rfc8693:
        subjectTokenType: "urn:ietf:params:oauth:token-type:jwt"
        requestedTokenType: "urn:ietf:params:oauth:token-type:access_token"
        audience: https://api.example.com
Keycloak compatibility

Keycloak requires rfc8693.subjectTokenType: "urn:ietf:params:oauth:token-type:access_token". Use this value instead of jwt when the authorization server is Keycloak.

Configuration Options​

FieldDescriptionDefaultRequired
claimsDefines the claims to validate in order to authorize the request.
Claims are evaluated against the exchanged access token returned by the authorization server, not against the subject token presented by the client.
The claims option can only be used with JWT-formatted tokens. (More information in the claims section)		""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 in the clientConfig section)""No
clientConfig.tls.certPEM-encoded certificate or a URN referencing a secret containing the certificate used to establish a TLS connection with the authorization server (More information in the clientConfig section)""No
clientConfig.tls.keyPEM-encoded key or a URN referencing a secret containing the key used to establish a TLS connection with the authorization server. (More information in the clientConfig section)""No
clientConfig.tls.insecureSkipVerifyDisables TLS certificate verification when communicating with the authorization server.
Useful for testing purposes but strongly discouraged for production. (More information in the clientConfig section)		""No
clientConfig.timeoutSecondsDefines the time before giving up requests to the authorization server.5No
clientConfig.maxRetriesDefines the number of retries for requests to the authorization server that fail.3No
clientIDDefines the client identifier used to authenticate to the authorization server. Required by entraID; required by rfc8693 when the authorization server needs client authentication.""No
clientSecretDefines the client secret used to authenticate to the authorization server.
For method: entraID, either clientSecret or entraID.clientCertificate must be set.
More information in the Storing secret values in Kubernetes secrets section.		""No
entraID.clientCertificate.certificateDefines the PEM-encoded client certificate used to sign the client assertion sent to Microsoft Entra ID. Only RSA certificates are supported. Required when entraID.clientCertificate is set.""No
entraID.clientCertificate.privateKeyDefines the PEM-encoded RSA private key matching entraID.clientCertificate.certificate. Required when entraID.clientCertificate is set.""No
entraID.scopesDefines the target scopes requested from Microsoft Entra ID (for example, api://downstream-app/.default). Required when method: entraID.[]No
forwardHeadersDefines the HTTP headers to add to requests and populates them with values extracted from the exchanged access token claims.
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 tokens.		[]No
methodSelects the token-exchange grant. One of rfc8693 or entraID. Only one of rfc8693 or entraID can be configured at the same time, matching the selected method.rfc8693No
rfc8693.actorTokenDefines the RFC 8693 actor_token sent when the exchange is performed on behalf of an actor. Requires rfc8693.actorTokenType.""No
rfc8693.actorTokenTypeDefines the RFC 8693 actor_token_type matching rfc8693.actorToken.""No
rfc8693.audienceDefines the RFC 8693 audience requested for the exchanged token.""No
rfc8693.clientAuthMethodPins how the client credentials are sent to the authorization server: in_header for HTTP Basic authentication, or in_params in the request body. Leave empty to auto-detect the method, which costs an extra request to the authorization server on every exchange when it does not accept HTTP Basic.""No
rfc8693.requestedTokenTypeDefines the RFC 8693 requested_token_type (for example, urn:ietf:params:oauth:token-type:access_token).""No
rfc8693.resourceDefines the RFC 8693 resource requested for the exchanged token.""No
rfc8693.scopesDefines the OAuth scopes requested from the authorization server. Sent as a space-separated list in the token request body.[]No
rfc8693.subjectTokenTypeDefines the RFC 8693 subject_token_type of the incoming token (for example, urn:ietf:params:oauth:token-type:jwt). Required when method: rfc8693.""No
store.keyPrefixDefines the prefix of the key for the entries that store the exchanged tokens.
An exchanged token is cached only when the authorization server returns expires_in.		""No
store.secretDefines the secret used to encrypt cached tokens at rest. Must be 16, 24, or 32 characters long. Required when store is set.""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 store 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
tokenSource.headerDefines the header name containing the subject token sent by the client.
Defaults to reading a Bearer token from the Authorization header when tokenSource is not set.		"Authorization"No
tokenSource.headerAuthSchemeDefines the scheme when using Authorization as header name.
Check out the Authorization header documentation.		"Bearer"No
tokenSource.queryDefines the query parameter name containing the subject token sent by the client.""No
tokenSource.cookieDefines the cookie name containing the subject token sent by the client.""No
urlDefines the token endpoint of the authorization server. For entraID, this is the tenant /oauth2/v2.0/token endpoint.""Yes
usernameClaimDefines the claim that will be evaluated to populate the clientusername in the access logs.
Evaluated against the exchanged access token, not the subject token.
The usernameClaim option can only be used with JWT-formatted tokens.		""No
Non-JWT exchanged tokens

When the authorization server returns an access token that is not JWT-formatted, claims, forwardHeaders, and usernameClaim cannot be used, and the middleware fails the request if any of them are configured.

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-token-exchange
spec:
plugin:
  oAuthTokenExchange:
    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.