Skip to content

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:

authSources:
  oidcSource:
    oidc:
      issuer: https://issuer.com
      clientID: client-id
      clientSecret: client-secret
[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.

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

issuerHost

Optional

The issuerHost overwrites the Host (host[:port]) used to contact the OpenID Connect provider. It is useful when the issuer is exposed through TraefikEE, to allow the OIDC middleware to communicate with the OpenID Connect provider directly.

authSources:
  oidcSource:
    oidc:
      issuerHost: issuer.com
[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc]
      issuerHost = "issuer.com"

clientID

Required, Default=""

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

authSources:
  oidcSource:
    oidc:
      clientID: client-id
[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.

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

pkce

Optional, Default=false

The pkce option enables the Proof Key for Code Exchange as described in RFC 7636.

authSources:
  oidcSource:
    oidc:
      pkce: true
[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc]
      pkce = true

tls

Optional

Defines the TLS configuration used for the secure connection to the OpenID Connect provider.

tls.caBundle

Optional, Default=""

An optional caBundle containing a PEM-encoded certificate bundle or a path to a file containing the certificate bundle used to establish a TLS connection with the OpenID Connect issuer.

Using a File

Note that TraefikEE does not watch for file changes. If caBundle is set to a file path, its content will be read once when the middleware is initialized.

authSources:
  oidcSource:
    oidc:
      tls:
        caBundle: |-
          -----BEGIN CERTIFICATE-----
          MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNV
          BAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl
          Y29kaW5nIG1lPyAgVGhpcyBpcyBvbmx5IGEgdGVzdCEhITERMA8GA1UEBwwISGFt
          aWx0b24xETAPBgNVBAgMCFBlbWJyb2tlMQswCQYDVQQGEwJCTTEPMA0GCSqGSIb3
          DQEJARYAMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJ9WRanG/fUvcfKiGl
          EL4aRLjGt537mZ28UU9/3eiJeJznNSOuNLnF+hmabAu7H0LT4K7EdqfF+XUZW/2j
          RKRYcvOUDGF9A7OjW7UfKk1In3+6QDCi7X34RE161jqoaJjrm/T18TOKcgkkhRzE
          apQnIDm0Ea/HVzX/PiSOGuertwIDAQABMAsGCSqGSIb3DQEBBQOBgQBzMJdAV4QP
          Awel8LzGx5uMOshezF/KfP67wJ93UW+N7zXY6AwPgoLj4Kjw+WtU684JL8Dtr9FX
          ozakE+8p06BpxegR4BR3FMHf6p+0jQxUEAkAyb/mVgm66TyghDGC6/YkiKoZptXQ
          98TwDIK/39WEB/V607As+KoYazQG8drorw==
          -----END CERTIFICATE-----
authSources:
  oidcSource:
    oidc:
      tls:
        caBundle: /etc/tls/ca-bundle.pem
[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc.tls]
      caBundle = """
-----BEGIN CERTIFICATE-----
MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNV
BAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl
Y29kaW5nIG1lPyAgVGhpcyBpcyBvbmx5IGEgdGVzdCEhITERMA8GA1UEBwwISGFt
aWx0b24xETAPBgNVBAgMCFBlbWJyb2tlMQswCQYDVQQGEwJCTTEPMA0GCSqGSIb3
DQEJARYAMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJ9WRanG/fUvcfKiGl
EL4aRLjGt537mZ28UU9/3eiJeJznNSOuNLnF+hmabAu7H0LT4K7EdqfF+XUZW/2j
RKRYcvOUDGF9A7OjW7UfKk1In3+6QDCi7X34RE161jqoaJjrm/T18TOKcgkkhRzE
apQnIDm0Ea/HVzX/PiSOGuertwIDAQABMAsGCSqGSIb3DQEBBQOBgQBzMJdAV4QP
Awel8LzGx5uMOshezF/KfP67wJ93UW+N7zXY6AwPgoLj4Kjw+WtU684JL8Dtr9FX
ozakE+8p06BpxegR4BR3FMHf6p+0jQxUEAkAyb/mVgm66TyghDGC6/YkiKoZptXQ
98TwDIK/39WEB/V607As+KoYazQG8drorw==
-----END CERTIFICATE-----
"""
[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc.tls]
      caBundle = "/etc/tls/ca-bundle.pem"
tls.insecureSkipVerify

Optional, Default=false

Disables TLS certificate verification when communicating with the OpenID Connect issuer. Useful for testing purposes but strongly discouraged for production.

authSources:
  oidcSource:
    oidc:
      tls:
        insecureSkipVerify: true
[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc.tls]
      insecureSkipVerify = true

timeout

Optional, Default="5s"

This option controls the time before giving up requests to the OpenID Connect issuer.

authSources:
  oidcSource:
    oidc:
      timeout: 15s
[authSources]
  [authSources.oidcSource.oidc]
    timeout = "15s"

maxRetries

Optional, Default=3

The number of retries for requests to the OpenID Connect issuer that fail.

authSources:
  oidcSource:
    oidc:
      maxRetries: 5
[authSources]
  [authSources.oidcSource.oidc]
    maxRetries = 5

discoveryParams

Optional, Default=""

A map of arbitrary query parameters to be added to the openid-configuration well-known URI during the discovery mechanism.

authSources:
  oidcSource:
    oidc:
      discoveryParams:
        hd: example.com
        mykey: myvalue
[authSources]
  [authSources.oidcSource]
    [authSources.oidcSource.oidc.discoveryParams]
      hd = example.com
      mykey = myvalue

Session Storage

An OpenID Connect Authentication middleware can use a persistent KV storage to store the HTTP sessions data instead of keeping all the state in cookies. It avoids cookies growing inconveniently large, which can lead to latency issues.

Below is an example of a reference of all the possible options when configuring a consul KV storage in the static configuration.

Info

The options are all the same for the three other storage types (etcd, zookeeper, and redis), except for namespace, and token.

stores:
  consulStore:
    # the value has to match one of the possible
    # kv store types (consul, etcd, zookeeper, and redis).
    consul:
      keyPrefix: traefikee
      endpoints:
        - 'localhost:8500'

      username: foo
      password: bar
      token: baz
      namespace: production

      tls:
        caBundle: path/to/ca.crt
        insecureSkipVerify: false
[stores]

  # the value has to match one of the possible
  # kv store types (consul, etcd, zookeeper, and redis).
  [stores.consulStore.consul]
    keyPrefix = "traefikee"
    endpoints = ["localhost:8500"]
    username = "foo"
    password = "bar"
    token = "baz"
    namespace = "production"

    [stores.consulStore.consul.tls]
      caBundle = "path/to/ca.crt"
      insecureSkipVerify = false

Info

stores were previously named sessionStorages. The old property is now deprecated and will be removed in a future release.

Store Options

Warning

In the examples below, storeType should be replaced by one of the possible store types: etcd, zookeeper, redis, consul.

endpoints

Required, Default=""

Defines how to access the KV Store.

stores:
  foo:
    storeType:
      endpoints:
        - "127.0.0.1:8500"
[stores]
  [stores.foo.storeType]
    endpoints = ["127.0.0.1:8500"]

keyPrefix

Optional, Default=""

KeyPrefix optionally configures the prefix of the key for the entries that store the sessions.

stores:
  foo:
    storeType:
      keyPrefix: "traefikee"
[stores]
  [stores.foo.storeType]
    keyPrefix = traefikee

username

Optional, Default=""

Defines a username to connect to the KV store.

stores:
  foo:
    storeType:
      username: "foo"
      password: "bar"
[stores]
  [stores.foo.storeType]
    username = foo
    password = bar

password

Optional, Default=""

Defines a password to connect to the KV store.

stores:
  foo:
    storeType:
      username: "foo"
      password: "bar"
[stores]
  [stores.foo.storeType]
    username: foo
    password: bar

tls

Optional

Defines the TLS configuration used for the secure connection to the KV store.

A (possibly empty) TLS section is necessary to connect to a TLS endpoint.

tls.caBundle

Optional, Default=""

An optional caBundle containing a PEM-encoded certificate bundle or a path to a file containing the certificate bundle used to establish a TLS connection with the KV store.

Using a File

Note that TraefikEE does not watch for file changes. If caBundle is set to a file path, its content will be read once when the KV store client is initialized.

stores:
  foo:
    storeType:
      tls:
        caBundle: |-
          -----BEGIN CERTIFICATE-----
          MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNV
          BAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl
          Y29kaW5nIG1lPyAgVGhpcyBpcyBvbmx5IGEgdGVzdCEhITERMA8GA1UEBwwISGFt
          aWx0b24xETAPBgNVBAgMCFBlbWJyb2tlMQswCQYDVQQGEwJCTTEPMA0GCSqGSIb3
          DQEJARYAMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJ9WRanG/fUvcfKiGl
          EL4aRLjGt537mZ28UU9/3eiJeJznNSOuNLnF+hmabAu7H0LT4K7EdqfF+XUZW/2j
          RKRYcvOUDGF9A7OjW7UfKk1In3+6QDCi7X34RE161jqoaJjrm/T18TOKcgkkhRzE
          apQnIDm0Ea/HVzX/PiSOGuertwIDAQABMAsGCSqGSIb3DQEBBQOBgQBzMJdAV4QP
          Awel8LzGx5uMOshezF/KfP67wJ93UW+N7zXY6AwPgoLj4Kjw+WtU684JL8Dtr9FX
          ozakE+8p06BpxegR4BR3FMHf6p+0jQxUEAkAyb/mVgm66TyghDGC6/YkiKoZptXQ
          98TwDIK/39WEB/V607As+KoYazQG8drorw==
          -----END CERTIFICATE-----
stores:
  foo:
    storeType:
      tls:
        caBundle: /etc/tls/ca-bundle.pem
[stores]
  [stores.foo]
    [stores.foo.storeType.tls]
      caBundle = """
-----BEGIN CERTIFICATE-----
MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNV
BAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl
Y29kaW5nIG1lPyAgVGhpcyBpcyBvbmx5IGEgdGVzdCEhITERMA8GA1UEBwwISGFt
aWx0b24xETAPBgNVBAgMCFBlbWJyb2tlMQswCQYDVQQGEwJCTTEPMA0GCSqGSIb3
DQEJARYAMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJ9WRanG/fUvcfKiGl
EL4aRLjGt537mZ28UU9/3eiJeJznNSOuNLnF+hmabAu7H0LT4K7EdqfF+XUZW/2j
RKRYcvOUDGF9A7OjW7UfKk1In3+6QDCi7X34RE161jqoaJjrm/T18TOKcgkkhRzE
apQnIDm0Ea/HVzX/PiSOGuertwIDAQABMAsGCSqGSIb3DQEBBQOBgQBzMJdAV4QP
Awel8LzGx5uMOshezF/KfP67wJ93UW+N7zXY6AwPgoLj4Kjw+WtU684JL8Dtr9FX
ozakE+8p06BpxegR4BR3FMHf6p+0jQxUEAkAyb/mVgm66TyghDGC6/YkiKoZptXQ
98TwDIK/39WEB/V607As+KoYazQG8drorw==
-----END CERTIFICATE-----
"""
[stores]
  [stores.foo]
    [stores.foo.storeType.tls]
      caBundle = "/etc/tls/ca-bundle.pem"
tls.insecureSkipVerify

Optional, Default=false

If insecureSkipVerify is true, the TLS connection to the KV store accepts any certificate presented by the server regardless of the hostnames it covers.

stores:
  foo:
    storeType:
      tls:
        insecureSkipVerify: true
[stores]
  [stores.foo.storeType.tls]
    insecureSkipVerify = true

Consul Specific Options

namespace

Optional, Default=""

The namespace option defines the namespace to query.

Warning

The namespace option only works with Consul Enterprise, which provides the Namespaces feature.

stores:
  foo:
    storeType:
      namespace: production
[stores]
  [stores.foo.storeType]
    namespace = "production"

token

Optional, Default=""

Defines a token with which to connect to Consul.

stores:
  foo:
    storeType:
      token: secret
[stores]
  [stores.foo.storeType]
    token = "secret"

Redis Specific Options

db

Optional, Default=0

Defines the database to be selected after connecting to the Redis.

stores:
  foo:
    storeType:
      db: 0
[stores]
  [stores.foo.storeType]
    db = 0

sentinel

Optional

Defines the Sentinel configuration used to interact with Redis Sentinel.

sentinel.masterName

Required

masterName is the name of the Sentinel master.

stores:
  foo:
    storeType:
      sentinel:
        masterName: my-master
[stores]
  [stores.foo.storeType.sentinel]
    masterName = "my-master"
sentinel.username

Optional

username is the username for Sentinel authentication.

stores:
  foo:
    storeType:
      sentinel:
        username: user
[stores]
  [stores.foo.storeType.sentinel]
    username = "user"
sentinel.password

Optional

password is the password for Sentinel authentication.

stores:
  foo:
    storeType:
      sentinel:
        password: password
[stores]
  [stores.foo.storeType.sentinel]
    password = "password"
sentinel.latencyStrategy

Optional, Default=false

latencyStrategy defines whether to route commands to the closest master or replica nodes (mutually exclusive with RandomStrategy and ReplicaStrategy).

stores:
  foo:
    storeType:
      sentinel:
        latencyStrategy: true
[stores]
  [stores.foo.storeType.sentinel]
    latencyStrategy = true
sentinel.randomStrategy

Optional, Default=false

randomStrategy defines whether to route commands randomly to master or replica nodes (mutually exclusive with LatencyStrategy and ReplicaStrategy).

stores:
  foo:
    storeType:
      sentinel:
        randomStrategy: true
[stores]
  [stores.foo.storeType.sentinel]
    randomStrategy = true
sentinel.replicaStrategy

Optional, Default=false

replicaStrategy Defines whether to route all commands to replica nodes (mutually exclusive with LatencyStrategy and RandomStrategy).

stores:
  foo:
    storeType:
      sentinel:
        replicaStrategy: true
[stores]
  [stores.foo.storeType.sentinel]
    replicaStrategy = true
sentinel.useDisconnectedReplicas

Optional, Default=false

useDisconnectedReplicas defines whether to use replicas disconnected with master when cannot get connected replicas.

stores:
  foo:
    storeType:
      sentinel:
        useDisconnectedReplicas: true
[stores]
  [stores.foo.storeType.sentinel]
    useDisconnectedReplicas = true

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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.source=oidcSource"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      source: oidcSource
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.source=oidcSource"
"labels": {
  "traefik.http.middlewares.test-oidc.plugin.oidcAuth.source": "oidcSource"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.source=oidcSource"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          source: oidcSource
[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.

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`)"
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
- "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`)"
"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`)"
}
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`)"
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`)
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.redirectUrl=/callback"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      redirectUrl: "/callback"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.redirectUrl=/callback"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.redirectUrl": "/callback"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.redirectUrl=/callback"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          redirectUrl: "/callback"
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    redirectUrl = "/callback"

scopes

Optional, Default=['openid']

The scopes to request. Must include openid.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.scopes=openid, myscope"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      scopes:
        - openid
        - myscope
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.scopes=openid, myscope"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.scopes": "openid, myscope"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.scopes=openid, myscope"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          scopes:
            - openid
            - myscope
[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.

Disabling Consent Prompt

When a prompt key is set to an empty string in the AuthParams, the prompt parameter is not added to the OAuth2 authorization URL. Which means the user won't be prompted for consent.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.hd=example.com"
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.mykey=myvalue"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      authParams:
        hd: example.com
        mykey: myvalue
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.hd=example.com"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.mykey=myvalue"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.hd": "example.com",
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.mykey": "myvalue"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.hd=example.com"
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.authParams.mykey=myvalue"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          authParams:
            hd: example.com
            mykey: myvalue
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.disableLogin=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      disableLogin: true
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.disableLogin=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.disableLogin": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.disableLogin=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          disableLogin: true
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.loginUrl=example.com/login"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      loginUrl: example.com/login
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.loginUrl=example.com/login"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.loginUrl": "example.com/login"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.loginUrl=example.com/login"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          loginUrl: example.com/login
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.logoutUrl=example.com/logout"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      logoutUrl: example.com/logout
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.logoutUrl=example.com/logout"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.logoutUrl": "example.com/logout"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.logoutUrl=example.com/logout"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          logoutUrl: example.com/logout
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    logoutUrl = example.com/logout

postLoginRedirectUrl

Optional, Default=""

If set and used in conjunction with loginUrl, the middleware will redirect to this URL after successful login. It can be a path (/after/login for example), a host and a path (example.com/after/login) or a complete URL (https://example.com/after/login).

Supported Schemes

Only http and https schemes are supported.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.postLoginRedirectUrl=example.com/after/login"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      postLoginRedirectUrl: example.com/login
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.postLoginRedirectUrl=example.com/after/login"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.postLoginRedirectUrl": "example.com/after/login"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.postLoginRedirectUrl=example.com/after/login"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          postLoginRedirectUrl: example.com/after/login
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    postLoginRedirectUrl = example.com/after/login

postLogoutRedirectUrl

Optional, Default=""

If set and used in conjunction with logoutUrl, the middleware will redirect to this URL after logout. It can be a path (/after/logout for example), a host and a path (example.com/after/logout) or a complete URL (https://example.com/after/logout).

Supported Schemes

Only http and https schemes are supported.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.postLogoutRedirectUrl=example.com/after/logout"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      postLogoutRedirectUrl: example.com/logout
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.postLogoutRedirectUrl=example.com/after/logout"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.postLogoutRedirectUrl": "example.com/after/logout"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.postLogoutRedirectUrl=example.com/after/logout"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          postLogoutRedirectUrl: example.com/after/logout
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    postLogoutRedirectUrl = example.com/after/logout

backchannelLogoutUrl

Optional, Default=""

The URL called by the OIDC provider when a user logs out (see https://openid.net/specs/openid-connect-rpinitiated-1_0.html#OpenID.BackChannel). It can be a path (/backchannel-logout for example), a host and a path (example.com/backchannel-logout) or a complete URL (https://example.com/backchannel-logout).

Experimental

This feature is currently in an experimental state and has been tested exclusively with the Keycloak OIDC provider.

Supported Schemes

Only http and https schemes are supported.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.backchannelLogoutUrl=example.com/backchannel-logout"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      backchannelLogoutUrl: example.com/backchannel-logout
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.backchannelLogoutUrl=example.com/backchannel-logout"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.backchannelLogoutUrl": "example.com/backchannel-logout"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.backchannelLogoutUrl=example.com/backchannel-logout"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          backchannelLogoutUrl: example.com/backchannel-logout
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    backchannelLogoutUrl = example.com/backchannel-logout

backchannelLogoutSessionsRequired

Optional, Default=false

This specifies whether the OIDC provider includes the sid (session ID) Claim in the Logout Token to identify the user session (see https://openid.net/specs/openid-connect-backchannel-1_0.html#BCRegistration). If omitted, the default value is false.

Experimental

This feature is currently in an experimental state and has been tested exclusively with the Keycloak OIDC provider.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.backchannelLogoutSessionsRequired=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      backchannelLogoutSessionsRequired: true
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.backchannelLogoutSessionsRequired=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.backchannelLogoutSessionsRequired": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.backchannelLogoutSessionsRequired=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          backchannelLogoutSessionsRequired: true
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    backchannelLogoutSessionsRequired = true

stateCookie.secret

Optional, Default=""

The encryption key used to secure state information, it must be 16, 24 or 32 characters long. TraefikEE generates one if none is provided.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secret=mysecret12345678"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        secret: "mysecret12345678"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secret=mysecret12345678"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secret": "mysecret12345678"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secret=mysecret12345678"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            secret: "mysecret12345678"
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.stateCookie]
      secret = "mysecret12345678"

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

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.name=mystatecookie-%s"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        name: "mystatecookie-%s"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.name=mystatecookie-%s"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.name": "mystatecookie-%s"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.name=mystatecookie-%s"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            name: "mystatecookie-%s"
[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
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.path=/docs"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        path: "/docs"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.path=/docs"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.path": "/docs"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.path=/docs"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            path: "/docs"
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.domain=example.com"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        domain: "example.com"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.domain=example.com"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.domain": "example.com"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.domain=example.com"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            domain: "example.com"
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.maxAge=600"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        maxAge: 600
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.maxAge=600"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.maxAge": "600"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.maxAge=600"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            maxAge: 600
[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.
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.sameSite=strict"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        sameSite: "strict"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.sameSite=strict"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.sameSite": "strict"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.sameSite=strict"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            sameSite: "strict"
[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).

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.httpOnly=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        httpOnly: true
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.httpOnly=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.httpOnly": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.httpOnly=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            httpOnly: true
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secure=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      stateCookie:
        secure: true
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secure=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secure": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.stateCookie.secure=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          stateCookie:
            secure: true
[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).

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.name=mysession-%s"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        name: "mysession-%s"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.name=mysession-%s"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.name": "mysession-%s"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.name=mysession-%s"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            name: "mysession-%s"
[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
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.path=/docs"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        path: "/docs"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.path=/docs"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.path": "/docs"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.path=/docs"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            path: "/docs"
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.domain=example.com"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        domain: "example.com"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.domain=example.com"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.domain": "example.com"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.domain=example.com"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            domain: "example.com"
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.expiry=86400"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        expiry: 86400
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.expiry=86400"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.expiry": "86400"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.expiry=86400"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            expiry: 86400
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sliding=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        sliding: true
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sliding=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sliding": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sliding=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            sliding: true
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.refresh=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        refresh: true
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.refresh=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.refresh": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.refresh=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            refresh: true
[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.
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sameSite=strict"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        sameSite: "strict"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sameSite=strict"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sameSite": "strict"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.sameSite=strict"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            sameSite: "strict"
[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).

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.httpOnly=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        httpOnly: true
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.httpOnly=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.httpOnly": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.httpOnly=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            httpOnly: true
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secure=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        secure: true
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secure=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secure": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secure=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            secure: true
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      secure = true

session.secret

Optional, Default=""

The encryption key used to secure session information, it must be 16, 24 or 32 characters long. TraefikEE generates one if none is provided.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secret=mysecret12345678"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        secret: "mysecret12345678"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secret=mysecret12345678"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secret": "mysecret12345678"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.secret=mysecret12345678"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            secret: "mysecret12345678"
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      secret = "mysecret12345678"

session.store

Optional, Default=""

If specified, store is the persistent KV storage where the session data and credentials (Access Token, etc) are to be stored, instead of directly on the session cookie. The session cookie then keeps a reference (session ID) to the KV store entry.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.store=consulStore"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      session:
        store: "consulStore"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.store=consulStore"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.store": "consulStore"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.session.store=consulStore"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          session:
            store: "consulStore"
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.session]
      store = "consulStore"

csrf

Optional

When enabled, a CSRF cookie, named traefikee-csrf-token, is bound to the OIDC session to protect service from CSRF attacks. It is based on the Signed Double Submit Cookie implementation as defined by the OWASP Foundation.

When the OIDC session is expired, the corresponding CSRF cookie is deleted. This means that a new CSRF token will be generated and sent to the client whenever the session is refreshed or recreated.

When a request is sent and uses a non-safe method (see RFC7231#section-4.2.1), the CSRF token value (extracted from the cookie) have to be sent to the server in the header configured with the headerName option.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      csrf: {}
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          csrf: {}
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.csrf]

csrf.secure

Optional, Default=false

Defines whether the CSRF cookie is only sent to the server when a request is made with the https scheme.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf.secure=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      csrf:
        secure: true
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf.secure=true"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf.secure": "true"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf.secure=true"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          csrf:
            secure: true
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.csrf]
      secure = true

csrf.headerName

Optional, Default="Traefikee-Csrf-Token"

Defines the name of the header used to send the CSRF token value received previously in the CSRF cookie.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf.headerName=X-Csrf-Token"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      csrf:
        headerName: X-Csrf-Token
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf.headerName=X-Csrf-Token"
"labels": {
  "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf.headerName": "X-Csrf-Token"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.csrf.headerName=X-Csrf-Token"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          csrf:
            headerName: X-Csrf-Token
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    [http.middlewares.test-oidc.plugin.oidcAuth.csrf]
      headerName = "X-Csrf-Token"

forwardHeaders

Optional, Default=None

The forwardHeaders option sets the HTTP headers to add to requests and populates them with values extracted from the ID Token claims and/or Access Token claims returned by the authentication server.

See the Claims section for the syntax specifics.

Note

Claims to be forwarded that are not found in the JWT result in empty headers.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Expires-At=exp"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      forwardHeaders:
        Group: grp
        Expires-At: exp
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Group=grp"
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Expires-At=exp"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Group": "grp",
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Expires-At": "exp"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Group=grp"
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.forwardHeaders.Expires-At=exp"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          forwardHeaders:
            Group: grp
            Expires-At: exp
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.username=userId"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      username: userId
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.username=userId"
"labels": {
    "traefik.http.middlewares.test-oidc.plugin.oidcAuth.username": "userId"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.username=userId"
http:
  middlewares:
    test-jwt:
      plugin:
        oidcAuth:
          username: userId
[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.

labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.claims=Equals(`grp`, `admin`)"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidcAuth:
      claims: Equals(`grp`, `admin`)
- "traefik.http.middlewares.test-oidc.plugin.oidcAuth.claims=Equals(`grp`, `admin`)"
"labels": {
  "traefik.http.middlewares.test-oidc.plugin.oidcAuth.claims": "Equals(`grp`, `admin`)"
}
labels:
  - "traefik.http.middlewares.test-oidc.plugin.oidcAuth.claims=Equals(`grp`, `admin`)"
http:
  middlewares:
    test-oidc:
      plugin:
        oidcAuth:
          claims: Equals(`grp`, `admin`)
[http.middlewares]
  [http.middlewares.test-oidc.plugin.oidcAuth]
    claims = "Equals(`grp`, `admin`)"
Syntax

The following functions are supported in claims. The first argument of the function, which represents the key to look for in the token claims, can be prefixed to specify which of the two kinds of token is inspected. Possible prefix values are id_token. and access_token.. If no prefix is specified, it defaults to the ID token.

Function Description Example
Equals Validates the equality of the value in key with value. Equals(`id_token.grp`, `admin`)
Prefix Validates the value in key has the prefix of value. Prefix(`access_token.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(`id_token.areas`, `home`)
SplitContains Validates the value in key contains the value once split by the separator. SplitContains(`access_token.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:

user.name
{
  "active": true,
  "grp": "admin",
  "scope": "reader writer deploy",
  "referrer": "http://example.com/foo/bar",
  "areas": [
    "office",
    "home"
  ],
  "user" {
    "name": "John Snow",
    "status": "undead"
  }
}
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:

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`)"
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`)
- "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`)"
"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`)"
}
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`)"
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`)
[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"