External LDAP directory

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 important. The LDAP authentication mechanism can be added using the CLI or the UI in Kommander.

The following example does not cover all possible configurations. Refer to the Dex LDAP connector reference documentation for more details.

The example below configures a DKP cluster to connect to the Online LDAP Test Server and for demonstration purposes, the configuration shown 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.

Below are steps for the CLI followed by UI in the event you prefer to use it.

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

   CODE

   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

   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.

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

   CODE

   kubectl apply -f ldap.yaml

   NOTE: UI - Deploy LDAP through Add Identity Provider screen within the UI.

3. Retrieve a list of connectors:

   CODE

   kubectl get connector.dex.mesosphere.io -A

4. Run the following command to verify that the LDAP connector was created successfully:

   CODE

   kubectl get Connector.dex.mesosphere.io -n kommander <LDAP-CONNECTOR-NAME> -o yaml

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.

UI - While LDAP authentication has been enabled, additional access rights will need to be configured through the Add Identity Provider screen in the UI using the documentation for Granting Access to Kubernetes and Kommander Resources.

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

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

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

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"

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))\""

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=[]"