Skip to main content

OpenID Connect Authentication

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

Configuration Example​

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`)
      csrf: {}

Configuration Options​

FieldDescriptionDefaultRequired
issuerDefines 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
redirectUrlDefines the URL used by the OpenID Connect provider to redirect back to the middleware once the authorization is complete. (More information here)""Yes
clientIDDefines the unique client identifier for an account on the OpenID Connect provider, must be set when the clientSecret option is set. (More information here)""Yes
clientSecretDefines the unique client secret for an account on the OpenID Connect provider, must be set when the clientID option is set. (More information here)""Yes
claimsDefines the claims to validate in order to authorize the request.
The claims option can only be used with JWT-formatted token. (More information here)		""No
usernameClaimDefines the claim that will be evaluated to populate the clientusername in the access logs.
The usernameClaim option can only be used with JWT-formatted token.		""No
identityDefines the claim whose value identifies the caller, used for cache partitioning by the semantic cache middleware.
For example, grp uses the grp claim. If the claim is missing from the token, the middleware resolves no identity for that request.		subNo
forwardHeadersDefines the HTTP headers to add to requests and populates them with values extracted from the access token claims returned by the authorization server.
Claims to be forwarded that are not found in the JWT result in empty headers.
The forwardHeaders option can only be used with JWT-formatted token. To see this option in action, check out the OIDC + RateLimit & DistributedRateLimit guide.		[]No
clientConfig.tls.caPEM-encoded certificate bundle or a URN referencing a secret containing the certificate bundle used to establish a TLS connection with the authorization server (More information here)""No
clientConfig.tls.certPEM-encoded certificate or a URN referencing a secret containing the certificate used to establish a TLS connection with the Vault server (More information here)""No
clientConfig.tls.keyPEM-encoded key or a URN referencing a secret containing the key used to establish a TLS connection with the Vault server. (More information here)""No
clientConfig.tls.insecureSkipVerifyDisables TLS certificate verification when communicating with the authorization server.
Useful for testing purposes but strongly discouraged for production. (More information here)		falseNo
clientConfig.timeoutSecondsDefines the time before giving up requests to the authorization server.5No
clientConfig.maxRetriesDefines the number of retries for requests to authorization server that fail.3No
pkceDefines the Proof Key for Code Exchange as described in RFC 7636.falseNo
discoveryParamsA map of arbitrary query parameters to be added to the openid-configuration well-known URI during the discovery mechanism.""No
trustedIssuerDefines the issuer value to validate in JWT tokens when the issuer URL reported by the discovery endpoint differs from the issuer in the tokens.
Allows discovery to work when there's a mismatch between the discovery URL and the token issuer, while still validating tokens against the expected issuer.
More information here.		""No
disableIssuerCheckDisables issuer validation in JWT tokens.
When set to true, the middleware does not validate that the issuer claim in JWT tokens matches the expected issuer.
Useful for debugging purposes but strongly discouraged for production environments.
More information here.		falseNo
scopesThe scopes to request. Must include openid.openidNo
authParamsA map of the arbitrary query parameters to be passed to the Authentication Provider.
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.		""No
disableLoginDisables redirections to the authentication provider
This can be useful for protecting APIs where redirecting to a login page is undesirable.		falseNo
loginUrlDefines 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).
Only http and https schemes are supported.		""No
logoutUrlDefines 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).
Only http and https schemes are supported.		""No
postLoginRedirectUrlIf 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).
Only http and https schemes are supported.		""No
postLogoutRedirectUrlIf 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).
Only http and https schemes are supported.		""No
backchannelLogoutUrlDefines 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).
Only http and https schemes are supported.
This feature is currently in an experimental state and has been tested exclusively with the Keycloak OIDC provider.		""No
backchannelLogoutSessionsRequiredThis 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.
This feature is currently in an experimental state and has been tested exclusively with the Keycloak OIDC provider.		falseNo
stateCookie.nameDefines the name of the state cookie."MIDDLEWARE_NAME-state"No
stateCookie.pathDefines the 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.		"/"No
stateCookie.domainDefines 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.		""No
stateCookie.maxAgeDefines the number of seconds after which the state cookie should expire.
A zero or negative number will expire the cookie immediately.		600No
stateCookie.sameSiteInformsbrowsers 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).
More information here.		laxNo
stateCookie.httpOnlyForbids 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).		trueNo
stateCookie.secureDefines whether the state cookie is only sent to the server when a request is made with the https scheme.falseNo
session.nameThe name of the session cookie."MIDDLEWARE_NAME-session"No
session.pathDefines the 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.		"/"No
session.domainSpecifies the hosts that are allowed to receive the cookie. If specified, then subdomains are always included. 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.		""No
session.expiryNumber of seconds after which the session should expire. A zero or negative number is prohibited.86400 (24h)No
session.slidingForces the middleware to renew the session cookie each time an authenticated request is received.trueNo
session.refreshEnables the access token refresh when it expires.trueNo
session.sameSiteInform 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).
More information here.		laxNo
session.httpOnlyForbids 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).		trueNo
session.secureDefines whether the session cookie is only sent to the server when a request is made with the https scheme.falseNo
store.keyPrefixDefines the prefix of the key for the entries that store the sessions.""No
session.store.redis.endpointsEndpoints of the Redis instances to connect to (example: redis.traefik-hub.svc.cluster.local:6379)""Yes
session.store.redis.usernameThe username Traefik Hub will use to connect to Redis""No
session.store.redis.passwordThe password Traefik Hub will use to connect to Redis""No
session.store.redis.databaseThe database Traefik Hub will use to store information.0No
session.store.redis.clusterEnable Redis Cluster""No
session.store.redis.tls.caBundleCustom CA bundle""No
session.store.redis.tls.certTLS certificate""No
session.store.redis.tls.keyTLS key""No
session.store.redis.tls.insecureSkipVerifyAllow skipping the TLS verificationfalseNo
session.store.redis.sentinel.masterSetName of the set of main nodes to use for main selection. Required when using Sentinel.""No
session.store.redis.sentinel.usernameUsername to use for sentinel authentication (can be different from username)""No
session.store.redis.sentinel.passwordPassword to use for sentinel authentication (can be different from password)""No
csrfWhen enabled, a CSRF cookie, named hub-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.
Moreinformation here.		""No
csrf.secureDefines whether the CSRF cookie is only sent to the server when a request is made with the https scheme.falseNo
csrf.headerNameDefines the name of the header used to send the CSRF token value received previously in the CSRF cookie.Hub-Csrf-TokenNo

redirectUrl​

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 URLRedirectURLResult
http://expl.co/cbackhttp://expl.co/cback

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

Request URLRedirectURLResult
https://scur.coexpl.co/cbackhttps://expl.co/cback

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

Request URLRedirectURLResult
https://scur.cohttp://expl.co/cbackhttp://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​

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]

claims​

Syntax​

The following functions are supported in claims:

FunctionDescriptionExample
EqualsValidates the equality of the value in key with value.Equals(`grp`, `admin`)
PrefixValidates the value in key has the prefix of value.Prefix(`referrer`, `http://example.com\`)
Contains (string)Validates the value in key contains value.Contains(`referrer`, `/foo/`)
Contains (array)Validates the key array contains the value.Contains(`areas`, `home`)
SplitContainsValidates the value in key contains the value once split by the separator.SplitContains(`scope`, ` `, `writer`)
OneOfValidates the key array contains one of the values.OneOf(`areas`, `office`, `lab`)

All functions can be joined by boolean operands. The supported operands are:

OperandDescriptionExample
&&Compares two functions and returns true only if both evaluate to true.Equals(`grp`, `admin`) && Equals(`active`, `true`)
||Compares two functions and returns true if either evaluate to true.Equals(`grp`, `admin`) || Equals(`active`, `true`)
!Returns false if the function is true, otherwise returns true.!Equals(`grp`, `testers`)

All examples will return true for the following data structure:

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

Nested Claims​

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

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

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

Handling a key that contains a ''

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

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.

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

clientConfig​

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

clientConfig.tls​

Storing secret values in Kubernetes secrets​

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

urn:k8s:secret:[name]:[valueKey]
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: test-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

Issuer Validation​

The OIDC middleware validates that the issuer claim in JWT tokens matches the expected issuer. This validation ensures that tokens are issued by the correct identity provider and prevents token substitution attacks.

In some scenarios, the issuer URL used for discovery differs from the issuer value in the JWT tokens. This can occur when:

  • Using an internal discovery URL (e.g., http://internal-oidc.default.svc.cluster.local) while tokens contain an external issuer (e.g., https://issuer.com)
  • The OIDC provider reports a different issuer in its discovery endpoint than what appears in the tokens

Using trustedIssuer​

The trustedIssuer option allows you to specify the issuer value that will be validated in JWT tokens, independent of the discovery URL. This enables discovery to work when there's a mismatch while maintaining issuer validation for security.

Using trustedIssuer when discovery URL differs from token issuer
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oauth2-client-creds
  namespace: apps
spec:
  plugin:
    oidc:
      issuer: "http://internal-oidc.default.svc.cluster.local"
      trustedIssuer: "https://issuer.com"
      redirectUrl: "/callback"
      clientID: "urn:k8s:secret:my-secret:clientId"
      clientSecret: "urn:k8s:secret:my-secret:clientSecret"

In this example, the middleware uses http://internal-oidc.default.svc.cluster.local for discovery, but validates that JWT tokens contain https://issuer.com as the issuer claim.

Using disableIssuerCheck​

The disableIssuerCheck option disables issuer validation entirely. When set to true, the middleware does not validate the issuer claim in JWT tokens.

Security Warning

Disabling issuer validation removes an important security check. Only use this option for debugging purposes. In production environments, use trustedIssuer instead to maintain security while handling issuer mismatches.

Disabling issuer check for debugging
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oauth2-debug
  namespace: apps
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"
      disableIssuerCheck: true

When disableIssuerCheck is set to true and no trustedIssuer is defined, no issuer validation is performed. This allows discovery to proceed even when there are issuer mismatches, but tokens are not validated against any issuer.

sameSite - Accepted values​

  • none: Thebrowser will send cookies with both cross-site requests and same-site requests.
  • strict: Thebrowser 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.

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.

Refer to the redis options to configure the Redis connection.

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

The following Redis modes are supported:

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

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.

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"

csrf​

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.