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

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.