OpenID Connect Google

This page describes how to configure a service using Google for authentication with OpenID as Access Control Policy.

Introduction to OpenID (Google)¶

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

It delegates the authentication to Google as an external provider 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.

This Access Control Policy (ACP) is a preconfigured OIDC using Google as an issuer and supports only email claims.

Credentials¶

To use the OIDC Google ACP, please follow the instructions of the Google Cloud documentation.

In the GCloud console:

Go to API&Service -> Credentials
Select the OAuth 2.0 Client IDs targeted web application
Set the callback URL, note the ClientID and the ClientSecret, you will need them for the ACP configuration.

Web Interface¶

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

Traefik Hub Agent

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

To create an OIDC Google ACP, select the Create a Policy or go to the creation page directly.

These are the required fields for creating an ACP.

Required fields¶

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

Field	Example	Description
Agent	`my-agent`	Reference to the agent on which the ACP will be created.
Method	OIDC	Authentication protocol to use in this ACP.
Provider	OIDC Google	OIDC provider to use in this ACP.
Identification Client Id	`xxxx.apps.googleusercontent.com`	Google OAuth 2.0 Client ID (cf Credentials.
Identification Client Secret	`GOCSPX-XXXXX`	The OAuth Client Secret. Only available with a non-Kubernetes cluster.
Identification Client Secret Name	`my-oidc-google-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`	Users will be redirected to this URL after they have authenticated with Google.
Identification Emails	`[email protected]`	Defines the list of allowed emails.

OIDC Secret¶

The Client Secret must be set for Kubernetes clusters

oidc-google-secret.yaml

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

Additional Parameters¶

These parameters allow you to configure the OIDC Google 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 sent 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 the minimal working configuration to create a basic Access Control Policy.

oidc-google-acp.yaml

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

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

oidc-google-secret.yaml

# oidc-google-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: oidc-google-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-google-acp.yml

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

kubectl get accesscontrolpolicy oidc-google-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-google-acp

Client ID¶

Required

spec.oidcGoogle.clientId

Google OAuth 2.0 Client ID (cf Credentials).

Example

spec:
  oidcGoogle:
    clientId: XXX

Secret¶

Required

spec.oidcGoogle.secret

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

Example

oidc-google-acp.yaml

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

oidc-google-secret.yaml

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

RedirectURL¶

spec.oidcGoogle.redirectURL

Users will be redirected to this URL after they have authenticated with Google.

Example

oidc-google-acp.yaml

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

Emails¶

Required

spec.oidcGoogle.emails

Defines the list of allowed emails.

Example

oidc-google-acp.yaml

spec:
  oidcGoogle:
    emails:
      - [email protected]

Forward Headers¶

spec.oidcGoogle.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-google-acp.yaml

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

AuthParams¶

spec.oidcGoogle.authParams

Sets additional request parameters sent to the identity provider.

Example

oidc-google-acp.yaml

spec:
  oidcGoogle:
    authParams:
      hd: example.org

LogoutURL¶

spec.oidcGoogle.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

oidc-google-acp.yaml

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

Session¶

Domain¶

spec.oidcGoogle.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-google-acp.yaml

spec:
  oidcGoogle:
    session:
      domain: example.org

Path¶

spec.oidcGoogle.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

oidc-google-acp.yaml

spec:
  oidcGoogle:
    session:
      path: /

Refresh¶

spec.oidcGoogle.session.refresh

When enabled, refresh the ID token when it expires.

Example

oidc-google-acp.yaml

spec:
  oidcGoogle:
    session:
      refresh: true

SameSite¶

spec.oidcGoogle.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-google-acp.yaml

spec:
  oidcGoogle:
    session:
      sameSite: lax

Secure¶

spec.oidcGoogle.session.secure

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

Example

oidc-google-acp.yaml

spec:
  oidcGoogle:
    session:
      secure: true

StateCookie¶

Domain¶

spec.oidcGoogle.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-google-acp.yaml

spec:
  oidcGoogle:
    stateCookie:
      domain: example.org

Path¶

spec.oidcGoogle.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

oidc-google-acp.yaml

spec:
  oidcGoogle:
    stateCookie:
      path: /

SameSite¶

spec.oidcGoogle.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-google-acp.yaml

spec:
  oidcGoogle:
    stateCookie:
      sameSite: lax

Secure¶

spec.oidcGoogle.stateCookie.secure

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

Example

oidc-google-acp.yaml

spec:
  oidcGoogle:
    stateCookie:
      secure: true