OAuth 2.0 Token Introspection Authentication¶

OAuth 2.0 Token Introspection allows Traefik Enterprise 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.

Authentication Source¶

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

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

YAML

authSources:
  oAuthIntroSource:
    oAuthIntrospection:
      url: https://localhost/oauth2/introspect
      authorizationHeader: Basic dGVzdDp0ZXN0

TOML

[authSources]
  [authSources.oAuthIntroSource]
    [authSources.oAuthIntroSource.oAuthIntrospection]
      url = "https://localhost/oauth2/introspect"
      authorizationHeader = "Basic dGVzdDp0ZXN0"

Authentication Source Options¶

`url`¶

Required, Default=""

The url is the full introspection endpoint URL. It must include the scheme and path.

YAML

authSources:
  oAuthIntroSource:
    oAuthIntrospection:
      url: https://localhost/oauth2/introspect

TOML

[authSources]
  [authSources.oAuthIntroSource]
    [authSources.oAuthIntroSource.oAuthIntrospection]
        url = "https://localhost/oauth2/introspect"

`authorizationHeader`¶

Optional, Default=""

The authorizationHeader is the authentication used to access the introspection server endpoint. The value is used as the Authorization header sent to the introspection server.

YAML

authSources:
  oAuthIntroSource:
    oAuthIntrospection:
      authorizationHeader: Basic dGVzdDp0ZXN0

TOML

[authSources]
  [authSources.oAuthIntroSource]
    [authSources.oAuthIntroSource.oAuthIntrospection]
        authorizationHeader = "Basic dGVzdDp0ZXN0"

`customHeaders`¶

Optional, Default=""

The customHeaders are user defined headers to send in every introspection request.

YAML

authSources:
  oAuthIntroSource:
    oAuthIntrospection:
      customHeaders:
        Custom-Header: test
        Source: traefikee

TOML

[authSources]
  [authSources.oAuthIntroSource]
    [authSources.oAuthIntroSource.oAuthIntrospection]
        [authSources.oAuthIntroSource.oAuthIntrospection.customHeaders]
            Custom-Header = "test"
            Source = "traefikee"

OAuth 2.0 Token Introspection Middleware¶

After declaring an OAuth 2.0 Token Introspection Authentication Source in the static configuration of the cluster, OAuth 2.0 Token Introspection middleware can be added to routers in the dynamic configuration:

Docker

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source=oAuthIntroSource"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      source: oAuthIntroSource

Consul Catalog

- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source=oAuthIntroSource"

Marathon

"labels": {
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source": "oAuthIntroSource"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source=oAuthIntroSource"

File (YAML)

http:
  middlewares:
    test-oauth-intro:
      plugin:
        oAuthIntrospection:
          source: oAuthIntroSource

File (TOML)

[http.middlewares]
  [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection]
    source = "oAuthIntroSource"

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-oauth-intro.plugin.oAuthIntrospection.source=oAuthIntroSource"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      source: oAuthIntroSource

Consul Catalog

- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source=oAuthIntroSource"

Marathon

"labels": {
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source": "oAuthIntroSource"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source=oAuthIntroSource"

File (YAML)

http:
  middlewares:
    test-oauth-intro:
      plugin:
        oAuthIntrospection:
          source: oAuthIntroSource

File (TOML)

[http.middlewares]
  [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection]
    source = "oAuthIntroSource"

`tokenQueryKey`¶

Optional, Default=""

The tokenQueryKey sets the middleware to look for the token to introspect in a specific query parameter if not found in the Authorization header. The middleware will always look in the Authorization header first.

Docker

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenQueryKey=tok"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      tokenQueryKey: tok

Consul Catalog

- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenQueryKey=tok"

Marathon

"labels": {
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenQueryKey": "tok"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenQueryKey=tok"

File (YAML)

http:
  middlewares:
    test-oauth-intro:
      plugin:
        oAuthIntrospection:
          tokenQueryKey: tok

File (TOML)

[http.middlewares]
  [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection]
    tokenQueryKey = "tok"

`tokenTypeHint`¶

Optional, Default=""

The tokenTypeHint is a hint to the introspection server as to what type of token is being introspected. Please refer to the official documentation for more details.

Docker

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenTypeHint=access_token"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      tokenTypeHint: access_token

Consul Catalog

- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenTypeHint=access_token"

Marathon

"labels": {
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenTypeHint": "access_token"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenTypeHint=access_token"

File (YAML)

http:
  middlewares:
    test-oauth-intro:
      plugin:
        oAuthIntrospection:
          tokenTypeHint: access_token

File (TOML)

[http.middlewares]
  [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection]
    tokenTypeHint = "access_token"

`forwardAuthorization`¶

Optional, Default=false

The forwardAuthorization option determines if the authorization headers will be forwarded or stripped from a request after it has been approved by the middleware.

Docker

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardAuthorization=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      forwardAuthorization: true

Consul Catalog

- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardAuthorization=true"

Marathon

"labels": {
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardAuthorization": "true"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardAuthorization=true"

File (YAML)

http:
  middlewares:
    test-oauth-intro:
      plugin:
        oAuthIntrospection:
          forwardAuthorization: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection]
    forwardAuthorization = true

`forwardHeaders`¶

Optional, Default=None

The forwardHeaders option sets the HTTP headers to add to requests and populates them with values extracted from an introspection response.

Docker

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Scope=scope"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      forwardHeaders:
        Group: grp
        Scope: scope

Consul Catalog

- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Group=grp"
- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Scope=scope"

Marathon

"labels": {
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Group": "grp",
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Scope": "scope"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Scope=scope"

File (YAML)

http:
  middlewares:
    test-oauth-intro:
      plugin:
        oAuthIntrospection:
          forwardHeaders:
            Group: grp
            Scope: scope

File (TOML)

[http.middlewares]
  [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection]
    [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders]
      Group = "grp"
      Scope = "scope"

`username`¶

Optional, Default=""

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

Docker

labels:
  - "traefik.http.middlewares.test--oauth-intro.plugin.oAuthIntrospection.username=userId"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test--oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      username: userId

Consul Catalog

- "traefik.http.middlewares.test--oauth-intro.plugin.oAuthIntrospection.username=userId"

Marathon

"labels": {
    "traefik.http.middlewares.test--oauth-intro.plugin.oAuthIntrospection.username": "userId"
}

Rancher

labels:
  - "traefik.http.middlewares.test--oauth-intro.plugin.oAuthIntrospection.username=userId"

File (YAML)

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

File (TOML)

[http.middlewares]
  [http.middlewares.test--oauth-intro.plugin.oAuthIntrospection]
    username = userId

`claims`¶

Optional, Default=""

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

Docker

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.claims=Equals(`grp`, `admin`)"

Kubernetes

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

Consul Catalog

- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.claims=Equals(`grp`, `admin`)"

Marathon

"labels": {
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.claims": "Equals(`grp`, `admin`)"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.claims=Equals(`grp`, `admin`)"

File (YAML)

http:
  middlewares:
    test-oauth-intro:
      plugin:
        oAuthIntrospection:
          claims: Equals(`grp`, `admin`)

File (TOML)

[http.middlewares]
  [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection]
    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-oauth-intro.plugin.oAuthIntrospection.source=oAuthIntroSource"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenQueryKey=tok"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenTypeHint=access_token"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Expires-At=exp"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.claims=Equals(`grp`, `admin`)"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oauth-intro
spec:
  plugin:
    oAuthIntrospection:
      source: oAuthIntroSource
      tokenQueryKey: tok
      tokenTypeHint: access_token
      forwardHeaders:
        Group: grp
        Expires-At: exp
      claims: Equals(`grp`, `admin`)

Consul Catalog

- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source=oAuthIntroSource"
- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenQueryKey=tok"
- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenTypeHint=access_token"
- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Group=grp"
- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Expires-At=exp"
- "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.claims=Equals(`grp`, `admin`)"

Marathon

"labels": {
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source": "oAuthIntroSource"
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenQueryKey": "tok"
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenTypeHint": "access_token"
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Group": "grp"
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Expires-At": "exp"
  "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.claims": "Equals(`grp`, `admin`)"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.source=oAuthIntroSource"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenQueryKey=tok"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.tokenTypeHint=access_token"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders.Expires-At=exp"
  - "traefik.http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.claims=Equals(`grp`, `admin`)"

File (YAML)

http:
  middlewares:
    test-oauth-intro:
      plugin:
        oAuthIntrospection:
          source: oAuthIntroSource
          tokenQueryKey: tok
          tokenTypeHint: access_token
          forwardHeaders:
            Group: grp
            Expires-At: exp
          claims: Equals(`grp`, `admin`)

File (TOML)

[http.middlewares]
  [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection]
    source = "oAuthIntroSource"
    tokenQueryKey = "tok"
    tokenTypeHint = "access_token"
    claims = "Equals(`grp`, `admin`)"
    [http.middlewares.test-oauth-intro.plugin.oAuthIntrospection.forwardHeaders]
      Group = "grp"
      Expires-At = "exp"

OAuth 2.0 Token Introspection Authentication¶

Authentication Source¶

Authentication Source Options¶

url¶

authorizationHeader¶

customHeaders¶

OAuth 2.0 Token Introspection Middleware¶

Middleware Options¶

source¶

tokenQueryKey¶

tokenTypeHint¶

forwardAuthorization¶

forwardHeaders¶

username¶

claims¶

Syntax¶

Nested claims¶

Advanced Configuration Example¶

`url`¶

`authorizationHeader`¶

`customHeaders`¶

`source`¶

`tokenQueryKey`¶

`tokenTypeHint`¶

`forwardAuthorization`¶

`forwardHeaders`¶

`username`¶

`claims`¶