Set up fleet member clusters for LDAP authentication

This document describes how cluster administrators or application operators can configure Kubernetes clusters to support authentication from a third-party Lightweight Directory Access Protocol (LDAP) provider, such as Microsoft Entra ID or Google LDAP. For more information, see About authentication using third-party identities .

Limitations

You must use a cluster type that supports LDAP .

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 Configure LDAP providers to authenticate to clusters .

Throughout this setup, you might need to refer to the documentation for your LDAP server. The following administrator guides explain configuration for some popular LDAP providers, including where to find the information you need to log in to the LDAP server and configure your clusters:

• OpenLDAP
• Microsoft Entra ID
• Microsoft Active Directory
• Google LDAP

Populate the LDAP service account secret

Your cluster needs a service account secret to authenticate to the LDAP server and retrieve user details. LDAP authentication supports the following mechanisms:

• Basic authentication, where you use a username and password.
• Client certificate authentication, where you use a client private key and client certificate.

You or your platform administrator should have this information about your provider from following Configure LDAP providers to authenticate to clusters . To make the LDAP server login information available to the cluster, you need to create a Kubernetes Secret that has the LDAP login details. The following examples show how to configure Secrets for both authentication types. The examples show the Secret being applied to the anthos-identity-service namespace.

This is an example of a basic authentication Secret configuration:

 apiVersion 
 : 
  
 v1 
 kind 
 : 
  
 Secret 
 metadata 
 : 
  
 name 
 : 
  
  SERVICE_ACCOUNT_SECRET_NAME 
 
  
 namespace 
 : 
  
 "anthos-identity-service" 
 type 
 : 
  
 kubernetes.io/basic-auth 
  
 # Make sure the type is correct 
 data 
 : 
  
 username 
 : 
  
  USERNAME 
 
  
 # Use a base64-encoded username 
  
 password 
 : 
  
  PASSWORD 
 
  
 # Use a base64-encoded password 

where, SERVICE_ACCOUNT_SECRET_NAME is the name you have chosen for this Secret. Replace the username and password values with the username and password you got in the previous step. USERNAME is a base64-encoded username PASSWORD is a base64-encoded password

This is an example of a client certificate Secret configuration:

 apiVersion 
 : 
  
 v1 
 kind 
 : 
  
 Secret 
 metadata 
 : 
  
 name 
 : 
  
  SERVICE_ACCOUNT_SECRET_NAME 
 
  
 namespace 
 : 
  
 anthos-identity-service 
 type 
 : 
  
 kubernetes.io/tls 
  
 # Make sure the type is correct 
 data 
 : 
  
 # the data is abbreviated in this example 
  
 tls.crt 
 : 
  
 | 
  
 MIIC2DCCAcCgAwIBAgIBATANBgkqh ... 
  
 tls.key 
 : 
  
 | 
  
 MIIEpgIBAAKCAQEA7yn3bRHQ5FHMQ ... 

Replace SERVICE_ACCOUNT_SECRET_NAME with the name you have chosen for this Secret. Replace the TLS certificate and key values with the encoded certificate and key values you got in the previous step.

The examples show the secret being applied to the anthos-identity-service namespace. By default, system components have permission to read Secrets in this namespace. To use another namespace, change the metadata in the secret and then add a new RBAC policy to grant the permission to read Secrets in that namespace to the default ServiceAccount in the anthos-identity-service namespace, as follows:

 --- 
 apiVersion 
 : 
  
 rbac.authorization.k8s.io/v1 
 kind 
 : 
  
 Role 
 metadata 
 : 
  
 namespace 
 : 
  
  NAMESPACE 
 
  
 name 
 : 
  
 ais-secret-reader-role 
 rules 
 : 
 - 
  
 apiGroups 
 : 
  
 [ 
 "" 
 ] 
  
 resources 
 : 
  
 [ 
 "secrets" 
 ] 
  
 verbs 
 : 
  
 [ 
 "get" 
 , 
 "list" 
 ] 
 --- 
 apiVersion 
 : 
  
 rbac.authorization.k8s.io/v1 
 kind 
 : 
  
 RoleBinding 
 metadata 
 : 
  
 name 
 : 
  
 ais-secret-reader-role-binding 
  
 namespace 
 : 
  
  NAMESPACE 
 
 roleRef 
 : 
  
 apiGroup 
 : 
  
 rbac.authorization.k8s.io 
  
 kind 
 : 
  
 Role 
  
 name 
 : 
  
 ais-secret-reader-role 
 subjects 
 : 
 - 
  
 kind 
 : 
  
 ServiceAccount 
  
 name 
 : 
  
 default 
  
 namespace 
 : 
  
 anthos-identity-service 
 --- 

Configure the cluster

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

• Information about the identity provider and the parameters it needs to return user information.
• The name and namespace of the Secret that you created and applied in the previous, which allows the cluster to authenticate to the LDAP server.

To configure your cluster, edit the default ClientConfig in the kube-public namespace:

 kubectl  
--kubeconfig  
 USER_CLUSTER_KUBECONFIG 
  
-n  
kube-public  
edit  
clientconfig  
default 

Replace USER_CLUSTER_KUBECONFIG with the path to the kubeconfig file for the cluster. If there are multiple contexts in the kubeconfig, the current context is used. You might need to reset the current context to the correct cluster before running the command.

The following shows the format for ClientConfig configuration:

  apiVersion 
 : 
  
 authentication.gke.io/v2alpha1 
 kind 
 : 
  
 ClientConfig 
 metadata 
 : 
  
 name 
 : 
  
 default 
  
 namespace 
 : 
  
 kube-public 
 spec 
 : 
  
  authentication 
 : 
  
 - 
  
 name 
 : 
  
  NAME 
 
  
 ldap 
 : 
  
 certificateAuthorityData 
 : 
  
  CERTIFICATE_AUTHORITY_DATA 
 
  
 connectionType 
 : 
  
  CONNECTION_TYPE 
 
  
 host 
 : 
  
  HOST_NAME 
 
  
 serviceAccountSecret 
 : 
  
 name 
 : 
  
  SERVICE_ACCOUNT_SECRET_NAME 
 
  
 namespace 
 : 
  
  NAMESPACE 
 
  
 type 
 : 
  
  SECRET_FORMAT 
 
  
 user 
 : 
  
 baseDN 
 : 
  
  BASE_DN 
 
  
 filter 
 : 
  
  FILTER 
 
  
 identifierAttribute 
 : 
  
  IDENTIFIER_ATTRIBUTE 
 
  
 loginAttribute 
 : 
  
  LOGIN_ATTRIBUTE 
 
  
 group 
 : 
  
 baseDN 
 : 
  
  BASE_DN 
 
  
 filter 
 : 
  
  FILTER 
 
  
 identifierAttribute 
 : 
  
  IDENTIFIER_ATTRIBUTE 
 
 

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 LDAP fields

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

What's next?

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