Set up clusters for GKE Identity Service with SAML

This document is for cluster administrators or 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.
...

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.