How to connect your cluster to an external LDAP directory

This guide shows you how to configure your DKP cluster so that users can log in with the credentials stored in an external LDAP directory service.

Step 1: Add LDAP connector

Each LDAP directory is set up in its own specific manner, so these steps are non-trivial. The following example does not cover all possible configurations. Refer to the Dex LDAP connector reference documentation for more details.

The following example configures a DKP cluster to connect to the Online LDAP Test Server.

  1. Create a YAML file (ldap.yaml) similar to the following:

    apiVersion: v1
    kind: Secret
    metadata:
      name: ldap-password
      namespace: kommander
    type: Opaque
    stringData:
      password: password
    ---
    apiVersion: dex.mesosphere.io/v1alpha1
    kind: Connector
    metadata:
      name: ldap
      namespace: kommander
    spec:
      enabled: true
      type: ldap
      displayName: LDAP Test
      ldap:
        host: ldap.forumsys.com:389
        insecureNoSSL: true
        bindDN: cn=read-only-admin,dc=example,dc=com
        bindSecretRef:
          name: ldap-password
        userSearch:
          baseDN: dc=example,dc=com
          filter: "(objectClass=inetOrgPerson)"
          username: uid
          idAttr: uid
          emailAttr: mail
        groupSearch:
          baseDN: dc=example,dc=com
          filter: "(objectClass=groupOfUniqueNames)"
          userMatchers:
          - userAttr: DN
            groupAttr: uniqueMember
          nameAttr: ou
    CODE

    NOTE: The value for the LDAP connector name parameter (here: LDAP Test) appears on one of the login buttons in the DKP UI. You should choose an expressive name.

    Also note that for demonstration purposes, the configuration shown above uses insecureNoSSL: true.

    In production, you should protect LDAP communication with a properly-configured transport layer security (TLS). When using TLS, the admin can add insecureSkipVerify: true to spec.ldap to skip server certificate verification, if needed.

  2. Run the following command to deploy the LDAP connector.

    kubectl apply -f ldap.yaml
    CODE

Step 2: Log in

  1. Visit https://<YOUR-CLUSTER-HOST>/token and initiate a login flow.

  2. On the login page choose the Log in with <ldap-name> button.

  3. Enter the LDAP credentials, and log in.

Troubleshooting

It is likely that the Dex LDAP connector configuration is not quite right from the start. In that case, you need to be able to debug the problem and iterate on it. The Dex log output contains helpful error messages as indicated by the following examples.

Errors during Dex startup

If the Dex configuration fragment provided results in an invalid Dex config, Dex does not properly start up. In that case, reviewing the Dex logs will provide error details. Use the following command to retrieve the Dex logs:

kubectl logs -f dex-66675fcb7c-snxb8  -n kommander
CODE

You may see an error similar to the following:

error parse config file /etc/dex/cfg/config.yaml: error unmarshaling JSON: parse connector config: illegal base64 data at input byte 0
CODE

Another reason for Dex not starting up correctly is that https://<YOUR-CLUSTER-HOST>/token throws a 5xx HTTP error response after timing out.

Errors upon login

Most problems with the Dex LDAP connector configuration become apparent only after a login attempt. A login failing from misconfiguration will result in an error page showing only Internal Server Error and Login error. You can then usually find the root cause by reading the Dex log, as shown in the following example:

kubectl logs -f dex-5d55b6b94b-9pm2d -n kommander
CODE

You can look for output similar to this example:

[...]
time="2019-07-29T13:03:57Z" level=error msg="Failed to login user: failed to connect: LDAP Result Code 200 \"Network Error\": dial tcp: lookup freeipa.example.com on 10.255.0.10:53: no such host"
CODE

Here, the directory’s DNS name was misconfigured, which should be easy to address.

A more difficult problem occurs when a login through Dex through LDAP fails because Dex was not able to find the specified user unambiguously in the directory. That could be the result of an invalid LDAP user search configuration. Here’s an example error message from the Dex log:

time="2019-07-29T14:21:27Z" level=info msg="performing ldap search cn=users,cn=compat,dc=demo1,dc=freeipa,dc=org sub (&(objectClass=posixAccount)(uid=employee))"
time="2019-07-29T14:21:27Z" level=error msg="Failed to login user: ldap: filter returned multiple (2) results: \"(&(objectClass=posixAccount)(uid=employee))\""
CODE

Solving problems like this requires you to review the directory structure carefully. (Directory structures can be very different between different LDAP setups.) Then you must carefully assemble a user search configuration matching the directory structure.

Notably, with some directories, it can be hard to distinguish between the cases “properly configured, and user not found” (login fails in an expected way) and “not properly configured, and therefore user not found” (login fails in an unexpected way).

Example for successful login

For comparison, here are some sample log lines issued by Dex after successful login:

time="2019-07-29T15:35:51Z" level=info msg="performing ldap search cn=accounts,dc=demo1,dc=freeipa,dc=org sub (&(objectClass=posixAccount)(uid=employee))"
time="2019-07-29T15:35:52Z" level=info msg="username \"employee\" mapped to entry uid=employee,cn=users,cn=accounts,dc=demo1,dc=freeipa,dc=org"
time="2019-07-29T15:35:52Z" level=info msg="login successful: connector \"ldap\", username=\"\", email=\"employee@demo1.freeipa.org\", groups=[]"
CODE