Skip to main content

OAuth 2.0 Token Introspection Authentication

OAuth 2.0 Token Introspection allows Traefik Hub to retrieve metadata about an access token from an OAuth 2.0 server with the Token Introspection extension.
The metadata can be used to restrict the access to applications. For more information please refer to the RFC.

Configuration Options​

tokenSource​

This option defines how the client token should be given.

note

At least one of the following options must be defined.

FieldDescriptionDefaultRequired
tokenSource.headerDefines the header name containing the secret sent by the client.""No
tokenSource.headerAuthSchemeDefines the scheme when using Authorization as header name.
Check out the Authorization header documentation.		""No
tokenSource.queryDefines the query parameter name containing the secret sent by the client.""No
tokenSource.cookieDefines the cookie name containing the secret sent by the client.""No
Requiring the secret to be passed as a Bearer token
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      tokenSource:
        header: Authorization
        headerAuthScheme: Bearer

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.

ValueDescriptionRequired
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 serverNo
clientConfig.tls.certPEM-encoded certificate or a URN referencing a secret containing the certificate used to establish a TLS connection with the Vault serverNo
clientConfig.tls.keyPEM-encoded key or a URN referencing a secret containing the key used to establish a TLS connection with the Vault server.No
clientConfig.tls.insecureSkipVerifyDisables 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]
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      clientConfig:
        tls:
          ca: "urn:k8s:secret:tls:ca"
          cert: "urn:k8s:secret:tls:cert"
          key: "urn:k8s:secret:tls:key"
          insecureSkipVerify: true

clientConfig.timeoutSeconds​

FieldDescriptionDefaultRequired
clientConfig.timeoutSecondsDefines the time before giving up requests to the authorization server.5No
Increasing the timeout
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      clientConfig:
        timeoutSeconds: 15

clientConfig.maxRetries​

FieldDescriptionDefaultRequired
clientConfig.maxRetriesDefines the number of retries for requests to authorization server that fail.3No
Increasing the maximum number of retries
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      clientConfig:
        maxRetries: 5

clientConfig.url​

FieldDescriptionDefaultRequired
clientConfig.urlDefines the introspection endpoint URL. It must include the scheme and path.""Yes
Defining the introspection endpoint URL
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      clientConfig:
        url: https://localhost/oauth2/introspect

clientConfig.headers​

FieldDescriptionDefaultRequired
clientConfig.headersDefines the headers to send in every introspection request. Values can be plain strings or a valid Go template.
Currently, a variable of type Request corresponding to the request being introspected is accessible in templates.		""No
Defining headers to send in every introspection request
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      clientConfig:
        headers:
          Authorization: Basic dGVzdDp0ZXN0
          Request-Host: {{ .Request.Host }}
          Request-Header-Foo: {{ .Request.Header.Get "Foo" }}
          Request-Query-Bar: {{ .Request.URL.Query.Get "bar" }}

clientConfig.tokenTypeHint​

FieldDescriptionDefaultRequired
clientConfig.tokenTypeHintDefines the type of token being introspected, sent as a hint to the introspection server.
Please refer to the official documentation for more details.		""No
Introscpecting access tokens
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      clientConfig:
        tokenTypeHint: access_token

forwardHeaders​

FieldDescriptionDefaultRequired
forwardHeadersDefines 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-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      forwardHeaders:
        Group: grp
        Expires-At: exp

forwardAuthorization​

FieldDescriptionDefaultRequired
forwardAuthorizationDefines whether the authorization header will be forwarded or stripped from a request after it has been approved by the middleware.falseNo
Forwarding the authorization header
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      forwardAuthorization: true

claims​

FieldDescriptionDefaultRequired
claimsDefines 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-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      claims: Equals(`grp`, `admin`)

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

usernameClaim​

FieldDescriptionDefaultRequired
usernameClaimDefines 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-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      usernameClaim: userId

Advanced Configuration Example​

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

Using custom claims validation and forward headers
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      tokenSource:
        header: Authorization
        headerAuthScheme: Bearer
      tokenTypeHint: access_token
      forwardHeaders:
        Group: grp
        Expires-At: exp
      claims: Equals(`grp`, `admin`)