OpenID Connect (OIDC)

OpenID authentication is only available through a Custom plan!

This page describes how to configure a service with OpenID Connect as Access Control Policy.

Introduction to OpenID¶

OpenID Connect (OIDC) is an identity protocol that utilizes the authorization and authentication mechanisms of OAuth 2.0.

It delegates the authentication to an external provider (for example, 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), 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 on this one.

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:

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 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, select the Create a Policy or go to the creation page directly.

The form contains general and method-specific fields.

Required fields¶

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	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	"Equals(`grp`, `admin`)"	Claims constraints used to authorize the request (cf: claims).

OIDC Secret¶

The Client Secret must be set for Kubernetes clusters

oidc-secret.yaml

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, select 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 a minimal and a common working configuration to create a basic Access Control Policy.

oidc-acp.yaml

apiVersion: hub.traefik.io/v1alpha1
kind: AccessControlPolicy
metadata:
  name: oidc-acp
spec:
  oidc:
    issuer: https://xxxx
    clientId: XXX
    secret:
      name: oidc-secret
      namespace: my-ns

oidc-acp-common.yaml

apiVersion: hub.traefik.io/v1alpha1
kind: AccessControlPolicy
metadata:
  name: oidc-acp
spec:
  oidc:
    issuer: https://accounts.google.com
    redirectUrl: /callback
    scopes:
      - openid
    session:
      expiry: 86400
      path: /
    clientId: "xxxx.apps.googleusercontent.com"
    secret:
      name: oidc-secret
      namespace: my-ns
    stateCookie:
      path: /

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

oidc-secret.yaml

# 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¶

Required

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¶

Required

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¶

Required

spec.oidc.clientId

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

Example

spec:
  oidc:
    clientId: XXX

Secret¶

Required

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

oidc-acp.yaml

spec:
  oidc:
    secret:
      name: oidc-secret
      namespace: my-ns

oidc-secret.yaml

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

oidc-acp.yaml

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

Scope¶

spec.oidc.scopes

The scopes to request. Must include openid.

Example

oidc-acp.yaml

spec:
  oidc:
    scopes:
      - openid
      - myscope

Claims¶

spec.oidc.claims

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

Example

oidc-acp.yaml

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

oidc-acp.yaml

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

AuthParams¶

spec.oidc.authParams

Sets additional request parameters send to the identity provider.

Example

oidc-acp.yaml

spec:
  oidc:
    authParams:
      hd: example.org

LogoutURL¶

spec.oidc.logoutUrl

The URL on which the session should be deleted 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

oidc-acp.yaml

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

oidc-acp.yaml

spec:
  oidc:
    session:
      domain: example.org

Path¶

spec.oidc.session.path

Indicates a URL path that must exist in the requested URL 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

oidc-acp.yaml

spec:
  oidc:
    session:
      path: /

Refresh¶

spec.oidc.session.refresh

When enabled, refresh the ID token when it expires.

Example

oidc-acp.yaml

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

oidc-acp.yaml

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

oidc-acp.yaml

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

oidc-acp.yaml

spec:
  oidc:
    stateCookie:
      domain: example.org

Path¶

spec.oidc.stateCookie.path

Indicates a URL path that must exist in the requested URL 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

oidc-acp.yaml

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

oidc-acp.yaml

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

oidc-acp.yaml

spec:
  oidc:
    stateCookie:
      secure: true