Set up GKE Identity Service with LDAP

This document is for cluster administrators or application operators setting up GKE Identity Service on their clusters. It tells you how to set up GKE Identity Service on your clusters with your preferred Lightweight Directory Access Protocol (LDAP) provider, including Microsoft Active Directory. It assumes that you or your platform administrator has already got login details for your LDAP provider following the instructions in Set up an LDAP provider for GKE Identity Service. To find out more about how GKE Identity Service works and other setup options, see the overview. To learn how to access a cluster using this service as a developer or other cluster user, see Access clusters with GKE Identity Service. GKE Identity Service with LDAP can be used with Google Distributed Cloud deployments on VMware (user clusters) and on bare metal only.

Before you begin

  1. 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, see the installation guide If you are using Cloud Shell as your shell environment for interacting with Google Cloud, these tools are installed for you.
  2. Ensure that you have initialized the gcloud CLI for use with your project.

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:

Populate the LDAP service account secret

GKE Identity Service needs a service account secret to authenticate to the LDAP server and retrieve user details. There are two types of service accounts permitted in LDAP authentication, basic auth (using a username and password to authenticate to the server) or client certificate (using a client private key and client certificate). You or your platform administrator should have this information about your provider from following Set up an LDAP provider for GKE Identity Service. To make the LDAP server login information available to GKE Identity Service, you need to create a Kubernetes Secret resource, with the login details from Set up an LDAP provider for GKE Identity Service. The following examples show how to configure Secrets for both service account types. The examples show the secret being applied to the anthos-identity-service namespace.

This is an example of a basic auth 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, which is our recommended approach. This is because by default GKE Identity Service has permission to read Secrets in anthos-identity-service. If you want to use another namespace, change the metadata in the secret and then add a new RBAC policy to grant GKE Identity Service permission to read Secrets in that 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

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. Your ClientConfig configuration also includes the secret name and namespace from the Secret that you created and applied in the previous section, allowing GKE Identity Service to authenticate to the LDAP server.

To apply the configuration to your cluster, edit the KRM default object of type 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_STRING
      ldap:
        host: HOST_NAME
        certificateAuthorityData: CERTIFICATE_AUTHORITY_DATA
        connectionType: CONNECTION_TYPE
        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

The following table describes the fields in the ClientConfig CRD:

Field Required Description Format
name yes A name to identify this LDAP configuration string
host yes Hostname or IP address of the LDAP server. Port is optional and will default to 389, if unspecified. For example, ldap.server.example.com or 10.10.10.10:389. string
certificateAuthorityData Required for certain LDAP connection types Contains a Base64 encoded, PEM formatted certificate authority certificate for the LDAP server. This must be provided only for ldaps and startTLS connections. string
connectionType yes LDAP connection type to use when connecting to the LDAP server. Defaults to startTLS. The insecure mode should only be used for development, since all communication with the server will be in plaintext. string
serviceAccountSecret
name yes Name of the Kubernetes Secret that stores the credentials for the LDAP service account. string
namespace yes Namespace of the Kubernetes Secret which stores the credentials for the LDAP service account. string
type yes Defines the format of the service account secret in order to support different kinds of secrets. If you specified basic-auth in your Secret configuration, this should be basic, otherwise it should be tls. If unspecified, defaults to basic. string
user
baseDN yes The location of the subtree in the LDAP directory to search for user entries. string
filter no Optional filter to apply when searching for the user. This can be used to further restrict the user accounts that are allowed to login. If unspecified, defaults to (objectClass=User). string
identifierAttribute no Determines which attribute to use as the user's identity after they are authenticated. This is distinct from the loginAttribute field to allow users to login with a username, but then have their actual identifier be an email address or full Distinguished Name (DN). For example, setting loginAttribute to sAMAccountName and identifierAttribute to userPrincipalName would allow a user to login as bsmith, but actual RBAC policies for the user would be written as bsmith@example.com. Using userPrincipalName is recommended since this will be unique for each user. If unspecified, this defaults to userPrincipalName. string
loginAttribute no The name of the attribute that matches against the input username. This is used to find the user in the LDAP database, for example (<LoginAttribute>=<username>) and is combined with the optional filter field. This defaults to userPrincipalName. string
group (Optional field)
baseDN yes The location of the subtree in the LDAP directory to search for group entries. string
filter no Optional filter to be used when searching for groups a user belongs to. This can be used to explicitly match only certain groups in order to reduce the amount of groups returned for each user. This defaults to (objectClass=Group). string
identifierAttribute no The identifying name of each group a user belongs to. For example, if this is set to distinguishedName then RBACs and other group expectations should be written as full DNs. If unspecified, this defaults to distinguishedName. string

What's next?

After the configuration is applied, continue to set up user access to clusters with GKE Identity Service.