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
- 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 installkubectl
, 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.
- The latest version of the Google Cloud CLI, which includes
- 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.