OpenID Connect Authentication

The OIDC Authentication middleware secures your applications by delegating the authentication to an external provider

Introduction

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.

Configuration Options

`issuer`

Field	Description	Default	Required
`issuer`	Defines the URL to the OpenID Connect provider (for example, `https://accounts.google.com`). It should point to the server which provides the OpenID Connect configuration.	" "	Yes

Referencing the Issuer
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret

`redirectUrl`

Field	Description	Default	Required
`redirectUrl`	Defines the URL used by the OpenID Connect provider to redirect back to the middleware once the authorization is complete.	" "	Yes

Add specific rule on the IngressRoute

The URL informs the OpenID Connect provider how to return to the middleware. 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.

Defining specific rule for redirectUrl
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: whoami
spec:
  entryPoints:
    - web
    - websecure
  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: test-oidc

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).
See the following examples.

Inherit the Protocol and Domain from the Request and Uses the Redirecturl’s Path

Request URL	RedirectURL	Result
`http://expl.co`	`/cback`	`http://expl.co/cback`

Inherit the Protocol from the Request and Uses the Redirecturl’s Domain and Path

Request URL	RedirectURL	Result
`https://scur.co`	`expl.co/cback`	`https://expl.co/cback`

Replace the Request URL with the Redirect URL since It Is an Absolute URL

Request URL	RedirectURL	Result
`https://scur.co`	`http://expl.co/cback`	`http://expl.co/cback`

Supported Schemes

Only http and https schemes are supported.

Defining the redirectUrl
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret

`clientID`, `clientSecret`

Field	Description	Default	Required
`clientID`	Defines the unique client identifier for an account on the OpenID Connect provider, must be set when the `clientSecret` option is set.	""	Yes
`clientSecret`	Defines the unique client secret for an account on the OpenID Connect provider, must be set when the `clientID` option is set.	""	Yes

Storing secret values in Kubernetes secrets

When configuring the clientID and the clientSecret, it is possible to reference Kubernetes secrets defined in the same namespace as the Middleware. The reference to a Kubernetes secret takes the form of a URN:

urn:k8s:secret:[name]:[valueKey]

Configuration
Kubernetes Secret

Referencing the Kubernetes secret
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: "urn:k8s:secret:my-secret:clientId"
      clientSecret: "urn:k8s:secret:my-secret:clientSecret"

Creating the Kubernetes secret
apiVersion: v1
kind: Secret
metadata:
  name: my-secret
stringData:
  clientID: my-oidc-client-name
  clientSecret: mysecret

`claims`

Field	Description	Default	Required
`claims`	Defines the claims to validate in order to authorize the request.	""	No

note

The claims option can only be used with JWT-formatted token.

Validating that clients are in the admin group
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      claims: Equals(`grp`, `admin`)

Syntax

The following functions are supported in claims:

Function	Description	Example
Equals	Validates 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:

JSON
{
  "active": true,
  "grp": "admin",
  "scope": "reader writer deploy",
  "referrer": "http://example.com/foo/bar",
  "areas": [
    "office",
    "home"
  ]
}

Nested Claims

Nested claims are supported by using a . between keys. For example:

Key

user.name

Claims
{
  "active": true,
  "grp": "admin",
  "scope": "reader writer deploy",
  "referrer": "http://example.com/foo/bar",
  "areas": [
    "office",
    "home"
  ],
  "user" {
    "name": "John Snow",
    "status": "undead"
  }
}

Result

John Snow

Handling keys that contain a '.'

If the key contains a dot, the dot can be escaped using \.

Handling a key that contains a ''

If the key contains a \, it needs to be doubled \\.

Access Token and ID Token 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.

Example	Description
Equals(`id_token.grp`, `admin`)	Checks if the value of claim `grp` in the ID token is `admin`.
Prefix(`access_token.referrer`, `http://example.com\`)	Checks if the value of claim `referrer` in the access token is prefixed by `http://example.com\`.
OneOf(`areas`, `office`, `lab`)	Checks if the value of claim `areas` in the ID token is `office` or `labs`.

`forwardHeaders`

Field	Description	Default	Required
`forwardHeaders`	Defines the HTTP headers to add to requests and populates them with values extracted from the access token claims returned by the authorization server.	[]	No

note

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

note

The forwardHeaders option can only be used with JWT-formatted token.

Forwarding the grp and exp claims as HTTP headers
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      forwardHeaders:
        Group: grp
        Expires-At: exp

`usernameClaim`

Field	Description	Default	Required
`usernameClaim`	Defines the claim that will be evaluated to populate the `clientusername` in the access logs.	""	No

note

The usernameClaim option can only be used with JWT-formatted token.

Defining the claim used to log the clientusername
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      usernameClaim: userId

`clientConfig`

Defines the configuration used to connect the API Gateway to a Third Party Software such as an Identity Provider.

`clientConfig.tls`

The table below lists the configuration options in Traefik Hub to define a TLS connection.

Value	Description	Required
`clientConfig.tls.ca`	PEM-encoded certificate bundle or a URN referencing a secret containing the certificate bundle used to establish a TLS connection with the authorization server	No
`clientConfig.tls.cert`	PEM-encoded certificate or a URN referencing a secret containing the certificate used to establish a TLS connection with the Vault server	No
`clientConfig.tls.key`	PEM-encoded key or a URN referencing a secret containing the key used to establish a TLS connection with the Vault server.	No
`clientConfig.tls.insecureSkipVerify`	Disables TLS certificate verification when communicating with the authorization server. Useful for testing purposes but strongly discouraged for production.	No

Storing secret values in Kubernetes secrets

When configuring the tls.ca, tls.cert, tls.key, it is possible to reference Kubernetes secrets defined in the same namespace as the Middleware.
The reference to a Kubernetes secret takes the form of a URN:

urn:k8s:secret:[name]:[valueKey]

Middleware configuration
Kubernetes TLS secret

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      clientConfig:
        tls:
          ca: "urn:k8s:secret:tls:ca"
          cert: "urn:k8s:secret:tls:cert"
          key: "urn:k8s:secret:tls:key"
          insecureSkipVerify: true

Kubernetes TLS Secret
apiVersion: v1
kind: Secret
metadata:
  name: tls
stringData:
  ca: |-
    -----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-----
  cert: |-
    -----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-----
  key: |-
    -----BEGIN EC PRIVATE KEY-----
    MHcCAQEEIC8CsJ/B115S+JtR1/l3ZQwKA3XdXt9zLqusF1VXc/KloAoGCCqGSM49
    AwEHoUQDQgAEpwUmRIZHFt8CdDHYm1ikScCScd2q6QVYXxJu+G3fQZ78ScGtN7fu
    KXMnQqVjXVRAr8qUY8yipVKuMCepnPXScQ==
    -----END EC PRIVATE KEY-----

`clientConfig.timeoutSeconds`

Field	Description	Default	Required
`clientConfig.timeoutSeconds`	Defines the time before giving up requests to the authorization server.	5	No

Increasing the timeout
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      clientConfig:
        timeoutSeconds: 15

`clientConfig.maxRetries`

Field	Description	Default	Required
`clientConfig.maxRetries`	Defines the number of retries for requests to authorization server that fail.	3	No

Increasing the maximum number of retries
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      clientConfig:
        maxRetries: 5

`pkce`

Field	Description	Default	Required
`pkce`	Defines the Proof Key for Code Exchange as described in RFC 7636.	false	No

Enabling PKCE
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      pkce: true

`discoveryParams`

Field	Description	Default	Required
`discoveryParams`	A map of arbitrary query parameters to be added to the openid-configuration well-known URI during the discovery mechanism.	" "	No

Setting a discvery parameter
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      discoveryParams:
        hubdisco: oidc-discovery

`scopes`

Field	Description	Default	Required
`scopes`	The scopes to request. Must include `openid`.	openid	No

Adding a custom scope
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      scopes:
        - openid
        - myscope

`authParams`

Field	Description	Default	Required
`authParams`	A map of the arbitrary query parameters to be passed to the Authentication Provider.	" "	No

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.

Setting Authentication Parameters
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      authParams:
        hd: example.com
        mykey: myvalue

`disableLogin`

Field	Description	Default	Required
`disableLogin`	Disables redirections to the authentication provider This can be useful for protecting APIs where redirecting to a login page is undesirable.	false	No

Disabling login
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      disableLogin: true

`loginUrl`

Field	Description	Default	Required
`loginUrl`	Defines 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`).	" "	No

Supported Schemes

Only http and https schemes are supported.

Defining the login URL
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      loginUrl: example.com/login

`logoutUrl`

Field	Description	Default	Required
`logoutUrl`	Defines 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`).	" "	No

Supported Schemes

Only http and https schemes are supported.

Defining the logout URL
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      logoutUrl: example.com/logout

`postLoginRedirectUrl`

Field	Description	Default	Required
`postLoginRedirectUrl`	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`).	" "	No

Supported Schemes

Only http and https schemes are supported.

Defining the post login redirect URL
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      postLoginRedirectUrl: example.com/login

`postLogoutRedirectUrl`

Field	Description	Default	Required
`postLogoutRedirectUrl`	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`).	" "	No

Supported Schemes

Only http and https schemes are supported.

Defining the post logout redirect URL
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      postLogoutRedirectUrl: example.com/logout

`backchannelLogoutUrl`

Field	Description	Default	Required
`backchannelLogoutUrl`	Defines 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`).	" "	No

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.

Defining the backchannel logout URL
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      backchannelLogoutUrl: example.com/backchannel-logout

`backchannelLogoutSessionsRequired`

Field	Description	Default	Required
`backchannelLogoutSessionsRequired`	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.	false	No

Experimental

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

Setting the backchannel logout session required
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      backchannelLogoutSessionsRequired: true

`stateCookie.name`

Field	Description	Default	Required
`stateCookie.name`	Defines the name of the state cookie.	"`MIDDLEWARE_NAME`-state"	No

Defining the state cookie name
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      stateCookie:
        name: "mystatecookie"

`stateCookie.path`

Field	Description	Default	Required
`stateCookie.path`	Defines the URL path that must exist in the requested URL in order to send the Cookie header.	"/"	No

Character '/'

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.

Defining the state cookie path
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      stateCookie:
        path: "/docs"

`stateCookie.domain`

Field	Description	Default	Required
`stateCookie.domain`	Defines the hosts that are allowed to receive the cookie.	" "	No

Sub-domains

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.

Defining the state cookie domain
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      stateCookie:
        domain: "example.com"

`stateCookie.maxAge`

Field	Description	Default	Required
`stateCookie.maxAge`	Defines the number of seconds after which the state cookie should expire. A zero or negative number will expire the cookie immediately.	600	No

Defining the state cookie max age
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      stateCookie:
        maxAge: 600

`stateCookie.sameSite`

Field	Description	Default	Required
`stateCookie.sameSite`	Informs 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).	lax	No

Accepted values

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.

Defining the state cookie cross-site strategy
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      stateCookie:
        sameSite: "strict"

`stateCookie.httpOnly`

Field	Description	Default	Required
`stateCookie.httpOnly`	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).	true	No

Disabling JS access to the state cookie
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      stateCookie:
        httpOnly: false

`stateCookie.secure`

Field	Description	Default	Required
`stateCookie.secure`	Defines whether the state cookie is only sent to the server when a request is made with the `https` scheme.	false	No

Setting the state cookie as a secured cookie
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      stateCookie:
        secure: true

`session.name`

Field	Description	Default	Required
`session.name`	The name of the session cookie.	"`MIDDLEWARE_NAME`-session"	No

Defining the session cookie name
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        name: "oidc-session"

`session.path`

Field	Description	Default	Required
`session.path`	Defines the URL path that must exist in the requested URL in order to send the Cookie header.	"/"	No

Character '/'

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.

Defining the session cookie path
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        path: "/docs"

`session.domain`

Field	Description	Default	Required
`session.domain`	Specifies the hosts that are allowed to receive the cookie. If specified, then subdomains are always included.	" "	No

Sub-domains

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.

Defining the session cookie domain
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        domain: "example.com"

`session.expiry`

Field	Description	Default	Required
`session.expiry`	Number of seconds after which the session should expire. A zero or negative number is prohibited.	86400 (24h)	No

Defining the session cookie expiry period
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        expiry: 86400

`session.sliding`

Field	Description	Default	Required
`session.sliding`	Forces the middleware to renew the session cookie each time an authenticated request is received.	true	No

Enabling the session cookie sliding option
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        sliding: true

`session.refresh`

Field	Description	Default	Required
`session.refresh`	Enables the access token refresh when it expires.	true	No

Enabling the session cookie sliding option
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        refresh: true

`session.sameSite`

Field	Description	Default	Required
`session.sameSite`	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).	lax	No

Accepted values

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.

Defining the session cookie cross-site strategy
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        sameSite: "strict"

`session.httpOnly`

Field	Description	Default	Required
`session.httpOnly`	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).	true	No

Disabling JS access to the session cookie
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        httpOnly: true

`session.secure`

Field	Description	Default	Required
`session.secure`	Defines whether the session cookie is only sent to the server when a request is made with the `https` scheme.	false	No

Setting the session cookie as a secured cookie
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        secure: true

`session.store`

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.

Connection parameters to your Redis server are attached to your Middleware deployment.

The following Redis modes are supported:

Single instance mode
Redis Cluster
Redis Sentinel

info

For more information about Redis, we recommend the official Redis documentation.

The table below lists the configuration options in Traefik Hub to connect to Redis and store middleware information.

Value	Description	Required
`redis.endpoints`	Endpoints of the Redis instances to connect to (example: `redis.traefik-hub.svc.cluster.local:6379`)	Yes
`redis.username`	The username Traefik Hub will use to connect to Redis	No
`redis.password`	The password Traefik Hub will use to connect to Redis	No
`redis.database`	The database Traefik Hub will use to sore information (default: `0`)	No
`redis.cluster`	Enable Redis Cluster	No
`redis.tls.caBundle`	Custom CA bundle	No
`redis.tls.cert`	TLS certificate	No
`redis.tls.key`	TLS key	No
`redis.tls.insecureSkipVerify`	Allow skipping the TLS verification	No
`redis.sentinel.masterSet`	Name of the set of main nodes to use for main selection. Required when using Sentinel.	No
`redis.sentinel.username`	Username to use for sentinel authentication (can be different from `username`)	No
`redis.sentinel.password`	Password to use for sentinel authentication (can be different from `password`)	No

info

If you use Redis in single instance mode or Redis Sentinel, you can configure the database field. This value won't be taken into account if you use Redis Cluster (only database 0 is available).

In this case, a warning is displayed, and the value is ignored.

Configuration
Kubernetes Secret

Defining Redis connection
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      session:
        store:
          redis:
            endpoints:
              - redis-master.traefik-hub.svc.cluster.local:6379
            password: "urn:k8s:secret:oidc:redisPass"

Creating the Kubernetes secret
apiVersion: v1
kind: Secret
metadata:
  name: oidc
stringData:
  redisPass: mysecret12345678

`csrf`

Field	Description	Default	Required
`csrf`	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.	" "	No

CSRF Internal Behavior

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.

Setting CSRF protection
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      csrf: {}

`csrf.secure`

Field	Description	Default	Required
`csrf.secure`	Defines whether the CSRF cookie is only sent to the server when a request is made with the `https` scheme.	false	No

Setting the CSRF cookie as a secured cookie
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      csrf:
        secure: true

`csrf.headerName`

Field	Description	Default	Required
`csrf.headerName`	Defines the name of the header used to send the CSRF token value received previously in the CSRF cookie.	TraefikHub-Csrf-Token	No

Setting the CSRF header name
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: my-oidc-client-name
      clientSecret: mysecret
      csrf:
        headerName: X-Csrf-Token

Advanced Configuration Example

Below is an advanced configuration example with custom session and state cookies using custom claims validation and forward headers:

Configuration
Kubernetes Secret

Configuration with custom session and state cookies using custom claims validation and forward headers
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-oidc
  namespace: whoami
spec:
  plugin:
    oidc:
      issuer: "https://tenant.auth0.com/realms/myrealm"
      redirectUrl: "/callback"
      clientID: "urn:k8s:secret:my-secret:clientId"
      clientSecret: "urn:k8s:secret:my-secret:clientSecret"
      session:
        name: customsessioncookiename
        sliding: false
        refresh: false
        expiry: 10
        sameSite: none
        httpOnly: false
        secure: true
      stateCookie:
        name: customstatecookiename
        maxAge: 10
        sameSite: none
        httpOnly: true
        secure: true
      forwardHeaders:
        Group: grp
        Expires-At: exp
      claims: Equals(`grp`, `admin`)

Creating the Kubernetes secret
apiVersion: v1
kind: Secret
metadata:
  name: my-secret
stringData:
  clientID: my-oidc-client-name
  clientSecret: mysecret

Introduction​

Configuration Options​

issuer​

redirectUrl​

Inherit the Protocol and Domain from the Request and Uses the Redirecturl’s Path​

Inherit the Protocol from the Request and Uses the Redirecturl’s Domain and Path​

Replace the Request URL with the Redirect URL since It Is an Absolute URL​

clientID, clientSecret​

claims​

Syntax​

Nested Claims​

forwardHeaders​

usernameClaim​

clientConfig​

clientConfig.tls​

clientConfig.timeoutSeconds​

clientConfig.maxRetries​

pkce​

discoveryParams​

scopes​

authParams​

disableLogin​

loginUrl​

logoutUrl​

postLoginRedirectUrl​

postLogoutRedirectUrl​

backchannelLogoutUrl​

backchannelLogoutSessionsRequired​

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.store​

csrf​

csrf.secure​

csrf.headerName​

Advanced Configuration Example​

Introduction

Configuration Options

`issuer`

`redirectUrl`

Inherit the Protocol and Domain from the Request and Uses the Redirecturl’s Path

Inherit the Protocol from the Request and Uses the Redirecturl’s Domain and Path

Replace the Request URL with the Redirect URL since It Is an Absolute URL

`clientID`, `clientSecret`

`claims`

Syntax

Nested Claims

`forwardHeaders`

`usernameClaim`

`clientConfig`

`clientConfig.tls`

`clientConfig.timeoutSeconds`

`clientConfig.maxRetries`

`pkce`

`discoveryParams`

`scopes`

`authParams`

`disableLogin`

`loginUrl`

`logoutUrl`

`postLoginRedirectUrl`

`postLogoutRedirectUrl`

`backchannelLogoutUrl`

`backchannelLogoutSessionsRequired`

`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.store`

`csrf`

`csrf.secure`

`csrf.headerName`

Advanced Configuration Example