Set up clusters for GKE Identity Service with SAML

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 a Security Assertion Markup Language (SAML) provider. The guide assumes that you have read the GKE Identity Service overview . The instructions in this document assume that GKE Identity Service has already been registered with your identity provider as a client application.

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.
Ensure that you have the following command line tools installed:
- Use the 466.0.0 version of the Google Cloud CLI or higher, 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.

Configure the cluster

GKE Identity Service uses a special Kubernetes custom resource type (CRD) to configure your clusters called ClientConfig, with fields for information about the identity provider and the parameters it needs to return user information.

kubectl

To edit your default ClientConfig, make sure you can connect to your cluster using 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 saml object as indicated in the snippet.

  apiVersion 
 : 
  
 authentication.gke.io/v2alpha1 
 kind 
 : 
  
 ClientConfig 
 metadata 
 : 
  
 name 
 : 
  
 default 
  
 namespace 
 : 
  
 kube-public 
 spec 
 : 
  
 authentication 
 : 
  
 - 
  
 name 
 : 
  
  NAME 
 
  
  
 saml 
 : 
  
 idpEntityID 
 : 
  
  ENTITY_ID 
 
  
 idpSingleSignOnURI 
 : 
  
  SIGN_ON_URI 
 
  
 idpCertificateDataList 
 : 
  
  IDP_CA_CERT 
 
  
 userAttribute 
 : 
  
  USER_ATTRIBUTE 
 
  
 groupsAttribute 
 : 
  
 { 
 '<var 
  
 name="user 
  
 attribute">GROUPS_ATTRIBUTE</var>' 
 } 
 } 
  
 userPrefix 
 : 
  
  USER_PREFIX 
 
  
 groupPrefix 
 : 
  
  GROUP_PREFIX 
 
  
 attributeMapping 
 : 
  
 ATTRIBUTE_KEY_1 
 : 
  
  ATTRIBUTE_CEL_EXPRESSION_1 
 
  
 ATTRIBUTE_KEY_2 
 : 
  
  ATTRIBUTE_CEL_EXPRESSION_2 
 
  
 certificateAuthorityData 
 : 
  
  CERTIFICATE_STRING 
 
  
 preferredAuthentication 
 : 
  
  PREFERRED_AUTHENTICATION 
 
  
 server 
 : 
  
<> # 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 saml object. The fields you need to add depend on your identity provider and the setup options chosen by your platform administrator 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
idpEntityID	Yes	The SAML entity ID for the SAML provider, specified in a URI format. For example: `https://www.idp.com/saml` .	URL String
idpSingleSignOnURI	yes	The SAML provider SSO endpoint, specified in a URI format. For example: `https://www.idp.com/saml/sso` .	URL String
idpCertificateDataList	Yes	Corresponds to the identity provider certificates used to verify the SAML response. These certificates must be standard base64 encoded and PEM formatted. Only a maximum of two certificates are supported to facilitate identity provider certificate rotation.	String
userAttribute	No	Name of the attribute in the SAML response that holds the username.	String
groupsAttribute	No	Name of the attribute in the SAML response that holds the user's group information.	String
userPrefix	No	The prefix you want to prepend to user claims to prevent clashes with existing names, if you don't want to use the default prefix.	String
groupPrefix	No	The prefix you want to prepend to security group names. This is to avoid clashes with existing names in your access control rules if you have configurations for multiple identity providers (typically the provider name).	String
attributeMapping	No	The mapping of additional user attributes.	String
certificateAuthorityData	No	If provided by your platform administrator, this is a PEM-encoded certificate string for the identity provider. Include the resulting string in `certificateAuthorityData` as a single line.	String
preferredAuthentication	No	Name of the preferred authentication method configured in the cluster.	String

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

What's next?

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