OpenID Connect Authentication¶

The OpenID Connect Authentication middleware secures your applications by delegating the authentication to an external provider (Google Accounts, LinkedIn, GitHub, etc.) and obtaining the end user's session claims and scopes for authorization purposes.

To authenticate the user, the middleware redirects through the authentication provider. Once the authentication is complete, users are redirected back to the middleware before being authorized to access the upstream application.

Encrypted Session Cookies

This middleware uses encrypted cookies to carry the session data.

OpenID Connect Authentication Diagram

Authentication Source¶

Before configuring an OpenID Connect Authentication middleware, an Authentication Source must be defined in the static configuration.

Below is an example of a minimal OpenID Connect Authentication Source that can be added to a static configuration:

YAML

authSources:
  oidcSource:
    oidc:
      issuer: https://issuer.com
      clientID: client-id
      clientSecret: client-secret

TOML

[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc]
      issuer = "https://issuer.com"
      clientID = "client-id"
      clientSecret = "client-secret"

Authentication Source Options¶

`issuer`¶

Required, Default=""

The issuer is the URL to the OpenID Connect provider (e.g.: https://accounts.google.com). It should point to the server which provides the OpenID Connect configuration.

YAML

authSources:
  oidcSource:
    oidc:
      issuer: https://issuer.com

TOML

[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc]
      issuer = "https://issuer.com"

`clientID`¶

Required, Default=""

The clientID is the unique client identifier for an account on the OpenID Connect provider.

YAML

authSources:
  oidcSource:
    oidc:
      clientID: client-id

TOML

[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc]
      clientID = "client-id"

`clientSecret`¶

Required, Default=""

The clientSecret is the unique client secret for an account on the OpenID Connect provider.

YAML

authSources:
  oidcSource:
    oidc:
      clientSecret: client-secret

TOML

[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc]
      clientSecret = "client-secret"

OpenID Connect Authentication Middleware¶

After declaring an OpenID Connect Authentication Source in the static configuration of the cluster, OpenID Connect Authentication middleware can be added to routers in the dynamic configuration.

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-oidc.plugin.oidcAuth.source=oidcSource"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      source: oidcSource

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.source=oidcSource"

Marathon

"labels": {
  "traefik.http.middlewares.test-oidc.plugin.oidcAuth.source": "oidcSource"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.source=oidcSource"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          source: oidcSource

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    source = "oidcSource"

`redirectUrl`¶

Required, Default=""

The redirect URL is the URL used by the OpenID Connect provider to redirect back to the middleware once the authorization is complete. Simply put, the URL informs the OpenID Connect provider how to return to the middleware. For the request to reach the middleware, it must be allowed in the router rule. If the router rule is accepting all paths on a domain, no extra work is needed. If the router rule is specific about the paths allowed, the path set in this option should be included.

Docker

labels:
  - "traefik.http.routers.login-router.entrypoints=http,https"
  - "traefik.http.routers.login-router.middlewares=oidcAuth"
  # Rules to match the loginUrl and redirectUrl can be added into
  # your current router.
  - "traefik.http.routers.login-router.rule=Path(`/myapi`) || Path(`/login`) || Path(`/callback`)"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: whoami
  namespace: traefikee
spec:
  entryPoints:
    - http
    - https
  routes:
      # Rules to match the loginUrl and redirectUrl can be added into
      # your current router.
    - match: Path(`/myapi`) || Path(`/login`) || Path(`/callback`)
      kind: Rule
      middlewares:
        - name: oidcAuth

Consul Catalog

- "traefik.http.routers.login-router.entrypoints=http,https"
- "traefik.http.routers.login-router.middlewares=oidcAuth"
  # Rules to match the loginUrl and redirectUrl can be added into
  # your current router.
- "traefik.http.routers.login-router.rule=Path(`/myapi`) || Path(`/login`) || Path(`/callback`)"

Marathon

"labels": {
  - "traefik.http.routers.login-router.entrypoints": "http, https",
  - "traefik.http.routers.login-router.middlewares": "oidcAuth",
  # Rules to match the loginUrl and redirectUrl can be added into
  # your current router.
  - "traefik.http.routers.login-router.rule": "Path(`/myapi`) || Path(`/login`) || Path(`/callback`)"
}

Rancher

labels:
  - "traefik.http.routers.login-router.entrypoints=http, https"
  - "traefik.http.routers.login-router.middlewares=oidcAuth"
  # Rules to match the loginUrl and redirectUrl can be added into
  # your current router.
  - "traefik.http.routers.login-router.rule=Path(`/myapi`) || Path(`/login`) || Path(`/callback`)"

File (YAML)

http:
  routers:
    login-router:
      entryPoints:
        - http
        - https
      middlewares:
        - oidcAuth
      # Rules to match the loginUrl and redirectUrl can be added into
      # your current router.
      rule: Path(`/myapi`) || Path(`/login`) || Path(`/callback`)

File (TOML)

[http]
  [http.routers]
    [http.routers.login-router]
      entryPoints = ["http", "https"]
      middlewares = ["oidcAuth"]
      # Rules to match the loginUrl and redirectUrl can be added into
      # your current router.
      rule = "Path(`/myapi`) || Path(`/login`) || Path(`/callback`)"

This URL will not be passed to the upstream application, but rather handled by the middleware itself. The chosen URL should therefore not conflict with any URLs needed by the upstream application.

This URL sometimes needs to be set in the OpenID Connect Provider's configuration as well (like for Google Accounts for example).

It can be the absolute URL, relative to the protocol (inherits the request protocol), or relative to the domain (inherits the request domain and protocol).

Request URL	RedirectURL	Result	Description
`http://expl.co`	`/cback`	`http://expl.co/cback`	The result inherits the protocol and domain from the request and uses the redirectURL's path
`https://scur.co`	`expl.co/cback`	`https://expl.co/cback`	The result inherits the protocol from the request and uses the redirectURL's domain and path
`https://scur.co`	`http://expl.co/cback`	`http://expl.co/cback`	The result replaces the request URL with the redirect URL since it is an absolute URL

Supported Schemes

Only http and https schemes are supported.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.redirectUrl=/callback"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      redirectUrl: "/callback"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.redirectUrl=/callback"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.redirectUrl": "/callback"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.redirectUrl=/callback"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          redirectUrl: "/callback"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    redirectUrl = "/callback"

`scopes`¶

Optional, Default=['openid']

The scopes to request. Must include openid.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.scopes=openid, myscope"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      scopes:
        - openid
        - myscope

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.scopes=openid, myscope"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.scopes": "openid, myscope"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.scopes=openid, myscope"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          scopes:
            - openid
            - myscope

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
      scopes = ["openid", "myscope"]

`authParams`¶

Optional, Default=""

A map of the arbitrary query parameters to be passed to the Authentication Provider.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.hd=example.com"
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.mykey=myvalue"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      authParams:
        hd: example.com
        mykey: myvalue

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.hd=example.com"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.mykey=myvalue"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.hd": "example.com",
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.mykey": "myvalue"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.hd=example.com"
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.mykey=myvalue"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          authParams:
            hd: example.com
            mykey: myvalue

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.authParams]
      hd = example.com
      mykey = myvalue

`disableLogin`¶

Optional, Default=false

Disables redirections to the authentication provider. This can be useful for protecting APIs where redirecting to a login page is undesirable.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.disableLogin=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      disableLogin: true

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.disableLogin=true"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.disableLogin": "true"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.disableLogin=true"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          disableLogin: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    disableLogin = true

`loginUrl`¶

Optional, Default=""

The URL used to start authorization when needed. All other requests that are not already authorized will return a 401 Unauthorized. When left empty, all requests can start authorization. It can be a path (/login for example), a host and a path (example.com/login) or a complete URL (https://example.com/login).

Supported Schemes

Only http and https schemes are supported.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.loginUrl=example.com/login"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      loginUrl: example.com/login

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.loginUrl=example.com/login"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.loginUrl": "example.com/login"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.loginUrl=example.com/login"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          loginUrl: example.com/login

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    loginUrl = example.com/login

`logoutUrl`¶

Optional, Default=""

The URL on which the session should be deleted in order to log users out. It can be a path (/logout for example), a host and a path (example.com/logout) or a complete URL (https://example.com/logout).

Supported Schemes

Only http and https schemes are supported.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.logoutUrl=example.com/logout"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      logoutUrl: example.com/logout

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.logoutUrl=example.com/logout"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.logoutUrl": "example.com/logout"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.logoutUrl=example.com/logout"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          logoutUrl: example.com/logout

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    logoutUrl = example.com/logout

`stateCookie.name`¶

Optional, Default="%s-state"

The name of the state cookie. This option supports limited templating in the form that a single %s flag can be specified, in which case the middleware replaces the %s flag with the source of the state cookie. (e.g.: mystatecookie-%s with a source called mysource will result in a cookie named mystatecookie-mysource).

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.name=mystatecookie-%s"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        name: "mystatecookie-%s"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.name=mystatecookie-%s"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.name": "mystatecookie-%s"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.name=mystatecookie-%s"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            name: "mystatecookie-%s"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.stateCookie]
      name = "mystatecookie-%s"

`stateCookie.path`¶

Optional, Default="/"

Indicates a URL path that must exist in the requested URL in order to send the Cookie header. The %x2F ("/") character is considered a directory separator, and subdirectories will match as well.

For example, if stateCookie.path is set to /docs, these paths will match:

/docs
/docs/web/
/docs/web/http

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.path=/docs"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        path: "/docs"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.path=/docs"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.path": "/docs"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.path=/docs"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            path: "/docs"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.stateCookie]
      path = "/docs"

`stateCookie.domain`¶

Optional, Default=""

Specifies the hosts that are allowed to receive the cookie. If specified, then subdomains are always included.

For example, if it is set to example.com, then cookies are included on subdomains like api.example.com.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.domain=example.com"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        domain: "example.com"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.domain=example.com"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.domain": "example.com"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.domain=example.com"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            domain: "example.com"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.stateCookie]
      domain = "example.com"

`stateCookie.maxAge`¶

Optional, Default=600

Number of seconds after which the state cookie should expire. A zero or negative number will expire the cookie immediately.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.maxAge=600"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        maxAge: 600

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.maxAge=600"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.maxAge": "600"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.maxAge=600"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            maxAge: 600

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.stateCookie]
      maxAge = 600

`stateCookie.sameSite`¶

Optional, Default="lax"

Inform browsers how they should handle the state cookie on cross-site requests. Setting it to lax or strict can provide some protection against cross-site request forgery attacks (CSRF).

Accepted values are the following:

none: The browser will send cookies with both cross-site requests and same-site requests.
strict: The browser will only send cookies for same-site requests (requests originating from the site that set the cookie). If the request originated from a different URL than the URL of the current location, none of the cookies tagged with the strict attribute will be included.
lax: Same-site cookies are withheld on cross-site subrequests, such as calls to load images or frames, but will be sent when a user navigates to the URL from an external site; for example, by following a link.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.sameSite=strict"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        sameSite: "strict"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.sameSite=strict"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.sameSite": "strict"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.sameSite=strict"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            sameSite: "strict"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.stateCookie]
      sameSite = "strict"

`stateCookie.httpOnly`¶

Optional, Default=true

Forbids JavaScript from accessing the cookie. For example, through the Document.cookie property, the XMLHttpRequest API, or the Request API. This mitigates attacks against cross-site scripting (XSS).

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.httpOnly=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        httpOnly: true

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.httpOnly=true"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.httpOnly": "true"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.httpOnly=true"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            httpOnly: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.stateCookie]
      httpOnly = true

`stateCookie.secure`¶

Optional, Default=false

A secure cookie is only sent to the server when a request is made with the https scheme.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secure=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        secure: true

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secure=true"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secure": "true"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secure=true"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            secure: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.stateCookie]
      secure = true

`session.name`¶

Optional, Default="%s-session"

The name of the session cookie. This option supports limited templating in the form that a single %s flag can be specified, in which case the middleware replaces the %s flag with the source of the session cookie. (e.g.: mysessioncookie-%s with a source called mysource will result in a cookie named mysessioncookie-mysource).

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.name=mysession-%s"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        name: "mysession-%s"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.name=mysession-%s"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.name": "mysession-%s"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.name=mysession-%s"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            name: "mysession-%s"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      name = "mysession-%s"

`session.path`¶

Optional, Default="/"

Indicates a URL path that must exist in the requested URL in order to send the Cookie header. The %x2F ("/") character is considered a directory separator, and subdirectories will match as well.

For example, if session.path is set to /docs, these paths will match:

/docs
/docs/web/
/docs/web/http

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.path=/docs"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        path: "/docs"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.path=/docs"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.path": "/docs"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.path=/docs"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            path: "/docs"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      path = "/docs"

`session.domain`¶

Optional, Default=""

Specifies the hosts that are allowed to receive the cookie. If specified, then subdomains are always included.

For example, if it is set to example.com, then cookies are included on subdomains like api.example.com.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.domain=example.com"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        domain: "example.com"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.domain=example.com"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.domain": "example.com"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.domain=example.com"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            domain: "example.com"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      domain = "example.com"

`session.expiry`¶

Optional, Default=86400 (24h)

Number of seconds after which the session should expire. A zero or negative number is prohibited.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.expiry=86400"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        expiry: 86400

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.expiry=86400"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.expiry": "86400"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.expiry=86400"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            expiry: 86400

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      expiry = 86400

`session.sliding`¶

Optional, Default=true

Tells the middleware to renew the session cookie each time an authenticated request is received.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sliding=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        sliding: true

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sliding=true"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sliding": "true"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sliding=true"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            sliding: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      sliding = true

`session.refresh`¶

Optional, Default=true

When enabled, refresh the access token when it expires.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.refresh=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        refresh: true

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.refresh=true"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.refresh": "true"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.refresh=true"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            refresh: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      refresh = true

`session.sameSite`¶

Optional, Default="lax"

Inform browsers how they should handle the session cookie on cross-site requests. Setting it to lax or strict can provide some protection against cross-site request forgery attacks (CSRF).

Accepted values are the following:

none: The browser will send cookies with both cross-site requests and same-site requests.
strict: The browser will only send cookies for same-site requests (requests originating from the site that set the cookie). If the request originated from a different URL than the URL of the current location, none of the cookies tagged with the strict attribute will be included.
lax: Same-site cookies are withheld on cross-site subrequests, such as calls to load images or frames, but will be sent when a user navigates to the URL from an external site; for example, by following a link.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sameSite=strict"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        sameSite: "strict"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sameSite=strict"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sameSite": "strict"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sameSite=strict"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            sameSite: "strict"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      sameSite = "strict"

`session.httpOnly`¶

Optional, Default=true

Forbids JavaScript from accessing the cookie. For example, through the Document.cookie property, the XMLHttpRequest API, or the Request API. This mitigates attacks against cross-site scripting (XSS).

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.httpOnly=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        httpOnly: true

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.httpOnly=true"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.httpOnly": "true"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.httpOnly=true"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            httpOnly: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      httpOnly = true

`session.secure`¶

Optional, Default=false

A secure cookie is only sent to the server when a request is made with the https scheme.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secure=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        secure: true

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secure=true"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secure": "true"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secure=true"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            secure: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      secure = true

`session.secret`¶

Required, Default=""

The encryption key used to secure session information, it must be 16, 24 or 32 characters long.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secret=mysecret12345678"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        secret: "mysecret12345678"

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secret=mysecret12345678"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secret": "mysecret12345678"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secret=mysecret12345678"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            secret: "mysecret12345678"

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      secret = "mysecret12345678"

`forwardHeaders`¶

Optional, Default=None

The forwardHeaders option sets the HTTP headers to add to requests and populates them with values extracted from the OpenID Connect Session.

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Expires-At=exp"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      forwardHeaders:
        Group: grp
        Expires-At: exp

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Group=grp"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Expires-At=exp"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Group": "grp",
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Expires-At": "exp"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Expires-At=exp"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          forwardHeaders:
            Group: grp
            Expires-At: exp

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders]
      Group = "grp"
      Expires-At = "exp"

`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-oidc.plugin.oidcAuth.username=userId"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      username: userId

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.username=userId"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.username": "userId"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.username=userId"

File (YAML)

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

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    username = userId

`claims`¶

Optional, Default=""

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

Docker

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.claims=Equals(`grp`, `admin`)"

Kubernetes

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

Consul Catalog

- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.claims=Equals(`grp`, `admin`)"

Marathon

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

Rancher

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.claims=Equals(`grp`, `admin`)"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          claims: Equals(`grp`, `admin`)

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    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-oidcAuth.plugin.oidcAuth.source=oidcSource"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.redirectUrl=example.com/callback"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.secret=mysupersecret123"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.samesite=lax"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.secure=true"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.forwardHeaders.Expires-At=exp"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.claims: Equals(`grp`, `admin`)"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidcAuth
spec:
  plugin:
    oidcAuth:
      source: oidcSource
      redirectUrl: example.com/callback
      session:
        secret: mysupersecret123
        samesite: lax
        secure: true
      forwardHeaders:
        Group: grp
        Expires-At: exp
      claims: Equals(`grp`, `admin`)

Consul Catalog

- "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.source=oidcSource"
- "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.redirectUrl=example.com/callback"
- "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.secret=mysupersecret123"
- "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.samesite=lax"
- "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.secure=true"
- "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.forwardHeaders.Group=grp"
- "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.forwardHeaders.Expires-At=exp"
- "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.claims: Equals(`grp`, `admin`)"

Marathon

"labels": {
    "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.source": "oidcSource",
    "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.redirectUrl": "example.com/callback",
    "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.secret": "mysupersecret123",
    "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.samesite": "lax",
    "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.secure": "true",
    "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.forwardHeaders.Group": "grp",
    "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.forwardHeaders.Expires-At": "exp",
    "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.claims": "Equals(`grp`, `admin`)"
}

Rancher

labels:
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.source=oidcSource"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.redirectUrl=example.com/callback"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.secret=mysupersecret123"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.samesite=lax"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.session.secure=true"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.forwardHeaders.Expires-At=exp"
  - "traefik.http.middlewares.test-oidcAuth.plugin.oidcAuth.claims: Equals(`grp`, `admin`)"

File (YAML)

http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          source: oidcSource
          redirectUrl: example.com/callback
          session:
            secret: mysupersecret123
            samesite: lax
            secure: true
          forwardHeaders:
            Group: grp
            Expires-At: exp
          claims: Equals(`grp`, `admin`)

File (TOML)

[http.middlewares]
  [http.middlewares.test-oidcAuth.plugin.oidcAuth]
    source = "oidcSource"
    redirectUrl = "example.com/callback"
    claims = "Equals(`grp`, `admin`)"
    [http.middlewares.test-oidcAuth.plugin.oidcAuth.session]
      secret = "mysupersecret123"
      samesite = "lax"
      secure = true
    [http.middlewares.test-oidcAuth.plugin.oidcAuth.forwardHeaders]
      Group = "grp"
      Expires-At = "exp"

OpenID Connect Authentication¶

Authentication Source¶

Authentication Source Options¶

issuer¶

clientID¶

clientSecret¶

OpenID Connect Authentication Middleware¶

Middleware Options¶

source¶

redirectUrl¶

scopes¶

authParams¶

disableLogin¶

loginUrl¶

logoutUrl¶

stateCookie.name¶

stateCookie.path¶

stateCookie.domain¶

stateCookie.maxAge¶

stateCookie.sameSite¶

stateCookie.httpOnly¶

stateCookie.secure¶

session.name¶

session.path¶

session.domain¶

session.expiry¶

session.sliding¶

session.refresh¶

session.sameSite¶

session.httpOnly¶

session.secure¶

session.secret¶

forwardHeaders¶

username¶

claims¶

Syntax¶

Nested claims¶

Advanced Configuration Example¶

`issuer`¶

`clientID`¶

`clientSecret`¶

`source`¶

`redirectUrl`¶

`scopes`¶

`authParams`¶

`disableLogin`¶

`loginUrl`¶

`logoutUrl`¶

`stateCookie.name`¶

`stateCookie.path`¶

`stateCookie.domain`¶

`stateCookie.maxAge`¶

`stateCookie.sameSite`¶

`stateCookie.httpOnly`¶

`stateCookie.secure`¶

`session.name`¶

`session.path`¶

`session.domain`¶

`session.expiry`¶

`session.sliding`¶

`session.refresh`¶

`session.sameSite`¶

`session.httpOnly`¶

`session.secure`¶

`session.secret`¶

`forwardHeaders`¶

`username`¶

`claims`¶