Console
    Contact Us Start free

    Set up clusters for GKE Identity Service with OIDC

    This document is for cluster administratorsor application operators who want to set up GKE Identity Service on individual clusters, allowing developers and other users to log in to the clusters using their existing identity details from an OpenID Connect (OIDC) provider.

    Prerequisites

    • Your cluster must be an GKE cluster on-premises (VMware or bare metal), on AWS, or on Azure. Per-cluster OIDC configuration is not supported for attached clusters or GKE clusters.
    • To authenticate through the Google Cloud console, each cluster that you want to configure for OIDC authentication must be registered to your project fleet .

    Before you begin

    • Ensure that your platform administrator has given you all the necessary information from Register GKE Identity Service with your provider before you start setup, including the client ID and secret for GKE Identity Service.

    • Ensure that you have the following command line tools installed:

      • The latest version of the Google Cloud CLI, which includes gcloud , the command line tool for interacting with Google Cloud. If you need to install the Google Cloud CLI, see the installation guide .
      • kubectl for running commands against Kubernetes clusters. If you need to install kubectl , follow these instructions .

      If you are using Cloud Shell as your shell environment for interacting with Google Cloud, these tools are installed for you.

    • Ensure that you have initialized the gcloud CLI for use with the project where the clusters are registered.

    • If you need to connect to an AWS or Azure GKE cluster's control plane that is outside your current VPC through a bastion host, make sure that you have created the bastion host and started an SSH tunnel at port 8118 before this setup. Then prepend your kubectl commands when following this guide with HTTPS_PROXY=http://localhost:8118 . If you used a different port when starting the SSH tunnel, replace 8118 with your selected port.

    Configure clusters

    To configure your clusters to use your chosen provider, GKE Identity Service needs you to specify details about the identity provider, the information in the JWT tokens it provides for user identification, and other information provided when you register GKE Identity Service as a client application.

    So, for example, if your provider creates identity tokens with the following fields (among others), where iss is the identity provider URI, sub identifies the user, and groupList lists the security groups that the user belongs to:

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

    ...your configuration will have the following corresponding fields:

    issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
...

    Your platform administrator, or whoever manages identity in your organization, should provide you with most of the information you need to create the configuration.

    GKE Identity Service uses a Kubernetes custom resource type (CRD) called ClientConfig for cluster configuration, with fields for all the information GKE Identity Service needs to interact with the identity provider. Each GKE cluster has a ClientConfig resource named default in the kube-public namespace that you update with your configuration details, following the instructions below.

    You can see some specific example configurations for popular providers in Provider-specific configurations .

    kubectl

    To edit your default ClientConfig, make sure you can connect to your cluster via kubectl , and 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 shown below. Do not 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_STRING 
 
  
 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. 
 ...

    You can configure multiple identity providers in your ClientConfig according to your requirements. This streamlines management and provides flexibility, letting you configure diverse authentication methods within a unified configuration resource. The following example ClientConfig defines multiple identity providers in the required order of authentication precedence.

     apiVersion: v1
items:
- apiVersion: authentication.gke.io/v2alpha1
  kind: ClientConfig
...
  spec:
    authentication:
    - aws:
        region: us-west-2
      name: AWS Login
    - ldap:
    ...
    - saml:
      ...
    - azureAD:
      ...
    - oidc:
      name: Okta OIDC
      ...
    -oidc:
      name: Google OIDC
      ...

    The following table describes the fields of the ClientConfig oidc object. Most of the fields are optional. The fields you need to add depend on your identity provider and the setup options chosen by your platform admin when configuring the provider for GKE Identity Service.

    Field Required Description Format
    name
    		 yes The name you want to use to identify this configuration, typically the identity provider name. A configuration name must start with a letter followed by up to 39 lowercase letters, numbers, or hyphens, and cannot end with a hyphen. String
    certificateAuthorityData
    		 No If provided by your platform administrator, a PEM-encoded certificate string for the identity provider. Include the resulting string in certificateAuthorityData as a single line. String
    clientID
    		 Yes The client ID returned when registering GKE Identity Service with your OIDC provider . String
    clientSecret
    		 No Shared secret between the OIDC client application and the OIDC provider. String
    deployCloudConsoleProxy
    		 No Specifies whether a proxy is deployed that lets the Google Cloud console connect to an on-premises identity provider that is not publicly accessible over the internet. By default this is set to false . Boolean
    extraParams
    		 No Additional key=value parameters to send to the identity provider, specified as a comma-separated list—for example `prompt=consent,access_type=offline`. Comma-delimited list
    groupsClaim
    		 No The JWT claim (field name) that your provider uses to return an account's security groups. String
    groupPrefix
    		 No The prefix you want to prepend to security group names to avoid clashes with existing names in your access control rules if you have configurations for multiple identity providers (typically the provider name). String
    issuerURI
    		 Yes The URI where authorization requests are made to your identity provider. The URI must use HTTPS and should not end with a trailing slash. URL String
    kubectlRedirectURI
    		 Yes The redirect URL and port used by the gcloud CLI and specified by your platform admin at registration, typically in the form http: // localhost:PORT/callback . URL String
    scopes
    		 Yes Additional scopes to send to the OpenID provider. For example, Microsoft Azure and Okta require the offline_access scope. Comma-delimited list
    userClaim
    		 No The JWT claim (field name) that your provider uses to identify a user account. If you don't specify a value here, GKE Identity Service uses "sub", which is the user ID claim used by many providers. You can choose other claims, such as "email" or "name", depending on the OpenID provider. Claims other than "email" are prefixed with the issuer URL to prevent naming clashes. String
    userPrefix
    		 No The prefix you want prepended to user claims to prevent clashes with existing names, if you don't want to use the default prefix. String
    enableAccessToken
    		 No If enabled, GKE Identity Service can use the identity provider's userinfo endpoint to get groups information when a user logs in from the command line. This lets you use security groups for authorization if you have a provider (such as Okta) that provides group claims from this endpoint. If not set, this is considered to be false . Boolean
    proxy
    		 No Proxy server address to use to connect to the identity provider, if applicable. You might need to set this if, for example, your cluster is in a private network and needs to connect to a public identity provider. For example: http://user:password@10.10.10.10:8888 . String

    After you complete your ClientConfig, save the file, which updates the ClientConfig on your cluster. If you make any syntax errors, you are prompted to re-edit the config to fix them.

    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.

    Azure AD

    This is the default configuration to set up GKE Identity Service with Azure AD. Using this configuration lets GKE Identity Service get user and group membership information from Azure AD, and lets you set up Kubernetes role based access control (RBAC) based on groups. However, using this configuration limits you to retrieving approximately 200 groups per user.

    If you need to retrieve more than 200 groups per user, see the instructions for Azure AD (Advanced).

      ... 
 spec 
 : 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
 oidc-azuread 
  
 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 
 # Rest of the resource is managed by Google. DO NOT MODIFY. 
 ...

    Replace the following:

    • CLIENT_ID : The client ID returned when registering GKE Identity Service with your provider .
    • CLIENT_SECRET : Shared secret between the OIDC client application and the OIDC provider.
    • TENANT : The kind of Azure AD account to be authenticated. Supported values are the tenant ID, or the tenant name for accounts belonging to a specific tenant. The tenant name is also known as the primary domain . For details on how to find these values, see Find the Microsoft Azure AD tenant ID and primary domain name .
    • PORT : The port number chosen for the redirect URL used by the gcloud CLI, specified by your platform admin at registration.

    Azure AD (Advanced)

    This optional configuration for Azure AD lets GKE Identity Service retrieve user and group information with no limit on the number of groups per user, using the Microsoft Graph API.

    For information on platforms that support this configuration, see Advanced setup for Azure AD .

    If you need to retrieve fewer than 200 groups per user, we recommend that you use the default configuration using an oidc anchor in your ClientConfig. For more information, see the instructions for Azure AD.

    All fields in the following example configuration are required.

      ... 
 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 
 
 # Rest of the resource is managed by Google. DO NOT MODIFY. 
 ...

    Replace the following:

    • NAME : The name you want to use to identify this configuration, typically the identity provider name. A configuration name must start with a letter followed by up to 39 lowercase letters, numbers, or hyphens, and cannot end with a hyphen.
    • PROXY_URL : Proxy server address to use to connect to the identity provider, if applicable. You might need to set this if, for example, your cluster is in a private network and needs to connect to a public identity provider. For example: http://user:password@10.10.10.10:8888 .
    • CLIENT_ID : The client ID returned when registering GKE Identity Service with your provider .
    • CLIENT_SECRET : Shared secret between the OIDC client application and the OIDC provider.
    • TENANT : The kind of Azure AD account to be authenticated. Supported values are the tenant ID, or the tenant name for accounts belonging to a specific tenant. The tenant name is also known as the primary domain . For details on how to find these values, see Find the Microsoft Azure AD tenant ID and primary domain name .
    • PORT : The port number chosen for the redirect URL used by the gcloud CLI, specified by your platform admin at registration.
    • GROUP_FORMAT : The format in which you want to retrieve group information. This field can take values corresponding to ID or NAME of the user groups. Note that this setting is currently available only for clusters in bare metal Google Distributed Cloud deployments.
    • USER_CLAIM (Optional): The JWT claim (field name) that your provider uses to identify an account. If you don't specify a value here, GKE Identity Service uses a value in the order of "email", "preferred_username", or "sub" to fetch the user details. This attribute can be used from GKE Enterprise version 1.28.

    Okta

    The following shows you how to set up authentication using both users and groups with Okta as your identity provider. This config lets Anthos Identity Service retrieve user and group claims by using an access token and Okta's userinfo endpoint.

      ... 
 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 
 # Rest of the resource is managed by Google. DO NOT MODIFY. 
 ...

    Group access limits

    For Okta users, Anthos Identity Service can retrieve group information for users whose group names, if concatenated, have a length less than 170000 characters. This corresponds to a membership of approximately 650 groups given Okta's maximum group length. If the user is a member of too many groups, the authentication call fails.

    What's next?

    After the configuration is applied, continue to set up user access to clusters .
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: