Skip to content

Open ID Connection Authentication

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

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

Credentials

To use the OIDC Access Control Policy (ACP), please configure your identity provider by defining at least a callback URL. Then get the Client ID and Client Secret from your provider.

Google Provider Example

To configure a Google Provider, you may use the preconfigured OIDC Google ACP, or take inspiration from its configuration.

Claims

The ID Token Claims Set represents a JSON object whose members are the claims conveyed by the Token.

Those claims can be used to authorize requests based on the following functions:

Function Description Example
Equals The value in key must be equal to value. Equals(`grp`, `admin`)
Prefix The value in key must start with the prefix of value. Prefix(`referrer`, `http://example.com`)
Contains (string) The value in key must contain value. Contains(`referrer`, `/foo/`)
Contains (array) The array in key must contain the value. Contains(`areas`, `home`)
SplitContains The value in key must contain the value once split by the separator. SplitContains(`scope`, ` `, `writer`)
OneOf The array in key must contain 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`) \
! Returns false if the function is true, otherwise returns true. !Equals(`grp`, `testers`)

All examples 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 dot (.) 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 dot (.)

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

Handling a key that contains a backslash ()

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

Web Interface

You can manage your Access Control Policies from the Traefik Hub UI.

Traefik Hub Agent

Creating any ACP requires you to have a connected Traefik Hub Agent. Please, refer to the installation guide for more information.

To create an OIDC Access Control Policy, click on the Create a Policy button at the top-right corner of the page or go to the creation page directly.

create acp

create oidc

The form contains general and method-specific fields.

Required

These are the required fields to fill to be able to create an Access Control Policy.

Field Example Description
Agent "my-agent" Refers to the agent on which the ACP will be created.
Method OIDC Authentication protocol to use in this ACP.
Provider Provider OIDC OIDC provider to use in this ACP.
Provider Issuer "https://accounts.google.com" 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.
Identification Client Id "xxxx.apps.googleusercontent.com" The unique client identifier for an account on the OpenID Connect provider (cf Credentials).
Identification Client Secret "GOCSPX-XXXXX" The OAuth Client Secret. Only available with a non-Kubernetes cluster.
Identification Client Secret Name "my-oidc-secret" The Name of the Kubernetes Secret used to store the OAuth Client Secret. Only available with a Kubernetes cluster.
Identification Client Secret Namespace "my-ns" The Namespace of the Kubernetes Secret used to store the OAuth Client Secret. Only available with a Kubernetes cluster
Identification Redirect URL "https:/example.org/callback" The redirect URL is the URL used by the OpenID Connect provider to redirect back to the agent once the authentication is complete.
Claims Scopes "openid","myscope" The scopes to request. Must include openid.
Claims Claims "Equals(grp, admin)" Claims constraints used to authorize the request (cf: claims).

OIDC Secret

The Client Secret must be set for Kubernetes clusters

apiVersion: v1
kind: Secret
metadata:
  name: oidc-secret
  namespace: my-ns
stringData:
  clientSecret: XXXX

Additional Parameters

These parameters allow you to configure the OIDC authentication deeper. They are not mandatory.

Field Example Description
Forward Headers "X-App-Group": "group" Sets the HTTP headers to add to requests and populates them with values extracted from the ID Token claims returned by the authentication server.
Auth Parameters "hd":"example.org" Sets additional request parameters send to the identity provider.

Note

Claims to be forwarded that are not found in the ID Token claims result in empty headers.

When all the fields are set up, click on the Save button to register the Access Control Policy on your cluster. The newly created ACP should be visible and manageable from the Access Control Policies listing page.

Custom Resource Definition

Custom Resource Definition is only available on Kubernetes.

Access Control Policies can be configured from Kubernetes manifest files containing a Traefik Hub custom resource. Custom Resource Definition contains resources that the Traefik Hub Agent can understand to manage ACPs.

The resource is called AccessControlPolicy from the hub.traefik.io group.

Here is the minimal working configuration to create a basic Access Control Policy.

apiVersion: hub.traefik.io/v1alpha1
kind: AccessControlPolicy
metadata:
  name: oidc-acp
spec:
  oidc:
    clientId: XXX
    secret:
      name: oidc-secret
      namespace: my-ns
    emails:
      - [email protected]

The following secret contains the OAuth Client Secret used by the ACP.

# oidc-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: oidc-secret
  namespace: my-ns
stringData:
  clientSecret: XXXX

To create the ACP, apply the manifest on the cluster using the Kubernetes CLI tool:

kubectl apply -f oidc-acp.yml

You are now able to see the ACP in the Traefik Hub UI, and in your Kubernetes cluster:

kubectl get accesscontrolpolicy oidc-acp

References

Name *

metadata.name

This is the name of the resource. The name is used to reference this resource in other Kubernetes resources and is also visible in the Traefik Hub UI.

The name should have less than 63 characters. It should contain only letters, numbers, and hyphens.

Example

metadata:
  name: oidc-acp

Issuer *

spec.oidc.issuer

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.

Example

spec:
  oidc:
    issuer: https://accounts.google.com

Client ID *

spec.oidc.clientId

The unique client identifier for an account on the OpenID Connect provider (cf Credentials).

Example

spec:
  oidc:
    clientId: XXX

Secret *

spec.oidc.secret

The name and namespace of the Kubernetes Secret used to store the OAuth Client Secret. The Secret must contain the OpenID Client Secret (cf Credentials).

Example

spec:
  oidc:
    secret:
      name: oidc-secret
      namespace: my-ns
apiVersion: v1
kind: Secret
metadata:
  name: oidc-secret
  namespace: my-ns
stringData:
  clientSecret: XXXX

RedirectURL

spec.oidc.redirectURL

The redirect URL is the URL used by the OpenID Connect provider to redirect back to the agent once the authentication is complete.

Example

spec:
  oidc:
    redirectURL: https://example.org/callback

Scope

spec.oidc.scopes

The scopes to request. Must include openid.

Example

spec:
  oidc:
    scopes:
      - openid
      - myscope

Claims

spec.oidc.claims

Claims constraints used to authorize the request (cf: claims).

Example

spec:
  oidc:
    claims: Equals(`grp`, `admin`)

Forward Headers

spec.oidc.forwardHeaders

Sets the HTTP headers to add to requests and populates them with values extracted from the ID Token claims returned by the authentication server.

Note

Claims to be forwarded that are not found in the ID Token claims result in empty headers.

Example

spec:
  oidc:
    forwardHeaders:
      X-App-Group: group

AuthParams

spec.oidc.authParams

Sets additional request parameters send to the identity provider.

Example

spec:
  oidc:
    authParams:
      hd: example.org 

LogoutURL

spec.oidc.logoutUrl

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

Example

spec:
  oidc:
    logoutUrl: https://example.org/logout

Session

Domain

spec.oidc.session.domain

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.

Example

spec:
  oidc:
    session:
      domain: example.org

Path

spec.oidc.session.path

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

Example

spec:
  oidc:
    session:
      path: /

Refresh

spec.oidc.session.refresh

When enabled, refresh the ID token when it expires.

Example

spec:
  oidc:
    session:
      refresh: true

SameSite

spec.oidc.session.sameSite

Informs 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 sub-requests, 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.

Example

spec:
  oidc:
    session:
      sameSite: lax

Secure

spec.oidc.session.secure

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

Example

spec:
  oidc:
    session:
      secure: true

StateCookie

Domain

spec.oidc.stateCookie.domain

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.

Example

spec:
  oidc:
    stateCookie:
      domain: example.org

Path

spec.oidc.stateCookie.path

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

Example

spec:
  oidc:
    stateCookie:
      path: /

SameSite

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

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.

Example

spec:
  oidc:
    stateCookie:
      sameSite: lax

Secure

spec.oidc.stateCookie.secure

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

Example

spec:
  oidc:
    stateCookie:
      secure: true