Set up fleet member clusters for OIDC authentication

This document describes how cluster administrators or application operators can configure clusters to support authentication using a third-party OpenID Connect (OIDC) provider.

Limitations

You must use a cluster type that supports OIDC .

Before you begin

1. Install the Google Cloud CLI.

2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

3. To initialize the gcloud CLI, run the following command:

   gcloud  
   init

4. After initializing the gcloud CLI, update it and install the required components:

   gcloud  
   components  
   update
   gcloud  
   components  
   install  
   kubectl

5. Ensure that your platform administrator has given you all of the provider information that you need. For more information, see Share the identity provider details .
6. To authenticate by using the Google Cloud console, register each cluster that you want to configure to your project fleet. For more information, see Fleet creation overview .
7. To connect to an AWS or Azure cluster's control plane that is outside your current VPC network through a bastion host, make sure that you have created the bastion host and started an SSH tunnel at port 8118 . When you run kubectl commands in this document, prepend the commands with HTTPS_PROXY=http://localhost: PORT , where PORT is the port number that you used when you started the SSH tunnel.
8. For GKE clusters on Google Cloud, register the clusters to your fleet .

Configure clusters

To configure authentication to a cluster using OIDC, you add the following information to a Kubernetes custom resource named ClientConfig:

• Information about your identity provider, such as a client ID and a secret.
• Information about the JSON Web Tokens (JWTs) that your identity provider uses for authentication.
• Any additional scopes or parameters that are unique to your identity provider.

For more information about the information that you need from your platform administrator, or whoever manages identity in your organization, see Share the identity provider details .

The cluster uses the fields in the ClientConfig custom resource to interact with your identity provider. Every cluster has a ClientConfig named default in the kube-public namespace. The specific fields that you modify depend on your identity provider.

To edit the default ClientConfig, make sure you can connect to your cluster kubectl , and then run the following command:

 kubectl  
--kubeconfig = 
 KUBECONFIG_PATH 
  
edit  
ClientConfigs  
default  
-n  
kube-public 

Replace KUBECONFIG_PATH with the path to your cluster's kubeconfig file—for example $HOME/.kube/config .

A text editor loads your cluster's ClientConfig resource. Add the spec.authentication.oidc object as show in the following sample. Don't modify any default data that has already been written.

  apiVersion 
 : 
  
 authentication.gke.io/v2alpha1 
 kind 
 : 
  
 ClientConfig 
 metadata 
 : 
  
 name 
 : 
  
 default 
  
 namespace 
 : 
  
 kube-public 
 spec 
 : 
  
  authentication 
 : 
  
 - 
  
 name 
 : 
  
  NAME 
 
  
 oidc 
 : 
  
 certificateAuthorityData 
 : 
  
  CERTIFICATE_AUTHORITY_DATA 
 
  
 clientID 
 : 
  
  CLIENT_ID 
 
  
 clientSecret 
 : 
  
  CLIENT_SECRET 
 
  
 deployCloudConsoleProxy 
 : 
  
  PROXY_BOOLEAN 
 
  
 extraParams 
 : 
  
  EXTRA_PARAMS 
 
  
 groupsClaim 
 : 
  
  GROUPS_CLAIM 
 
  
 groupPrefix 
 : 
  
  GROUP_PREFIX 
 
  
 issuerURI 
 : 
  
  ISSUER_URI 
 
  
 kubectlRedirectURI 
 : 
  
  KUBECTL_REDIRECT_URI 
 
  
 scopes 
 : 
  
  SCOPES 
 
  
 userClaim 
 : 
  
  USER_CLAIM 
 
  
 userPrefix 
 : 
  
  USER_PREFIX 
 
  
 enableAccessToken 
 : 
  
  ENABLE_ACCESS_TOKEN 
 
  
 proxy 
 : 
  
  PROXY_URL 
 
 # Rest of the resource is managed by Google. DO NOT MODIFY. 
 

For example, consider the following identity token fields:

 {
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  # Multiple lines are omitted here
} 

In this example, iss is the identity provider URI, sub identifies the user, and groupList lists the security groups that the user belongs to. This example shows only a sample of the fields that the actual token might have.

For the preceding example token, you update the following fields in the spec.authentication.oidc object of the ClientConfig:

 issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
# Multiple lines are omitted here 

You can add multiple OIDC, LDAP, and SAML identity provider configurations to the same ClientConfig. The cluster attempts to authenticate with each configuration in the order in which they are defined, and stops after the first successful authentication. The following example ClientConfig defines multiple identity providers in a specific order:

 apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - aws:
      region: us-west-2
    name: AWS Login
  - ldap:
  # Multiple lines are omitted here.
  - saml:
  # Multiple lines are omitted here.
  - azureAD:
  # Multiple lines are omitted here.
  - oidc:
    name: Okta OIDC
  # Multiple lines are omitted here.
  - oidc:
    name: Google OIDC
  # Multiple lines are omitted here. 

ClientConfig OIDC fields

The following table describes the fields of the ClientConfig oidc object. The fields that you need to add depend on your identity provider tokens and how your platform administrator configured the provider.

After you edit your ClientConfig, save the file to update the ClientConfig for your cluster. If you make any syntax errors, you see a prompt to fix those errors and save the file.

Provider-specific configurations

This section provides configuration guidance for some popular OIDC providers, including example configurations that you can copy and edit with your own details.

  # Multiple lines are omitted here. 
 spec 
 : 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
 oidc-entraid 
  
 oidc 
 : 
  
 clientID 
 : 
  
  CLIENT_ID 
 
  
 clientSecret 
 : 
  
  CLIENT_SECRET 
 
  
 cloudConsoleRedirectURI 
 : 
  
 https://console.cloud.google.com/kubernetes/oidc 
  
 extraParams 
 : 
  
 prompt=consent, access_type=offline 
  
 issuerURI 
 : 
  
 https://login.microsoftonline.com/ TENANT_ID 
/v2.0 
  
 kubectlRedirectURI 
 : 
  
 http://localhost: PORT 
/callback 
  
 scopes 
 : 
  
 openid,email,offline_access 
  
 userClaim 
 : 
  
 email 
 # Multiple lines are omitted here. Do not modify any pre-filled data. 
 

  # Multiple lines are omitted here. 
 spec 
 : 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
  NAME 
 
  
 proxy 
 : 
  
  PROXY_URL 
 
  
 azureAD 
 : 
  
 clientID 
 : 
  
  CLIENT_ID 
 
  
 clientSecret 
 : 
  
  CLIENT_SECRET 
 
  
 tenant 
 : 
  
  TENANT_ID 
 
  
 kubectlRedirectURI 
 : 
  
 http://localhost: PORT 
/callback 
  
 groupFormat 
 : 
  
  GROUP_FORMAT 
 
  
 userClaim 
 : 
  
  USER_CLAIM 
 
 # Multiple lines are omitted here. Do not modify any pre-filled data. 
 

  # Multiple lines are omitted here. 
 spec 
 : 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
 okta 
  
 oidc 
 : 
  
 clientID 
 : 
  
  CLIENT_ID 
 
  
 clientSecret 
 : 
  
  CLIENT_SECRET 
 
  
 cloudConsoleRedirectURI 
 : 
  
 https://console.cloud.google.com/kubernetes/oidc 
  
 enableAccessToken 
 : 
  
 true 
  
 extraParams 
 : 
  
 prompt=consent 
  
 groupsClaim 
 : 
  
 groups 
  
 issuerURI 
 : 
  
 https:// OKTA_ISSUER_URI 
/ 
  
 kubectlRedirectURI 
 : 
  
 http://localhost: PORT 
/callback 
  
 scopes 
 : 
  
 offline_access,email,profile,groups 
  
 userClaim 
 : 
  
 email 
 # Multiple lines are omitted here. Do not modify any pre-filled data. 
 

What's next?

After the configuration is applied, continue to set up user access to clusters .