Skip to content

LDAP#

You can configure LDAP (Lightweight Directory Access Protocol) for MKE 4 through the authentication.ldap section of the mke4.yaml configuration file.

LDAP example configuration:

authentication:
  ldap:
    enabled: true
    host: ldap.example.org:389
    insecureNoSSL: true
    bindDN: cn=admin,dc=example,dc=org
    bindPW: password
    usernamePrompt: Email Address
    userSearch:
      baseDN: ou=People,dc=example,dc=org
      filter: "(objectClass=person)"
      username: mail
      idAttr: DN
      emailAttr: mail
      nameAttr: cn

Info

The example configuration sets bindPW inline for brevity. Refer to Supply Authentication Credentials to learn the recommended method for providing the bind password.

Configure LDAP service using the command line#

In the mke4.yaml configuration file authentication.ldap section, enable your LDAP service by setting enabled to true. Use the remaining fields, which are defined in the following table, to configure the interactions with your LDAP server.

Info

For information on how to obtain the field values, refer to setting up OpenLDAP as an LDAP provider.

Field                                                            Description
host Host and optional port of the LDAP server, in the host:port format.
caData The trusted root certificate in PEM format (the certificate text itself).
bindDN Distinguished Name (DN) for an application service account.
bindPW Password for an application service account. Refer to Supply Athentication Credentials for information on how to provide the password.
usernamePrompt Attribute to display in the password prompt.
userSearch Settings to map user-entered username and password to an LDAP entry.
userSearch.baseDN BaseDN from which to start the search.
userSearch.filter Optional filter to apply for a user search of the directory.
userSearch.username Username attribute to use for user entry comparison.
userSearch.idAttr String representation of the user.
userSearch.emailAttr Attribute to map to email.
userSearch.nameAttr Attribute to map to display name of a user.
userSearch.preferredUsernameAttr Attribute to map to preferred usernames.
groupSearch Group search queries for groups given a user entry.
groupSearch.baseDN BaseDN from which to start the search.
groupSearch.filter Optional filter to apply for a group search of the directory.
groupSearch.userMatchers Field pairs list to use to match a user to a group.
groupSearch.nameAttr Group name.
noSimplePagination Set to true for an LDAP server that does not support the Simple Paged Results control (RFC 2696).

Default: false.

Refer to To disable simple pagination for more information.

Note

The LDAP trust certificate is a public configuration, not a credential. For more information, refer to the official DEX documentation LDAP configuration.

To disable simple pagination:

By default, MKE 4 paginates the LDAP searches that it performs when it synchronizes users and groups from your directory, using the Simple Paged Results control extension defined in RFC 2696. This keeps the synchronization of large directories reliable, and works with every modern LDAP server.

Some directory servers, however, do not support the control, or mishandle it. Such servers can reject a paginated searchs outright, or return an incomplete or empty result set without reporting an error. In such cases, users and groups are missing after synchronization. This behavior is typical of older Active Directory deployments and legacy directory products. For such a server, set noSimplePagination to true to have MKE 4 issue unpaginated searches instead:

For such a server, set noSimplePagination to true to have MKE 4 issue unpaginated searches instead:

authentication:
  ldap:
    enabled: true
    host: ldap.example.org:636
    noSimplePagination: true
    userSearch:
      baseDN: ou=People,dc=example,dc=org
      filter: "(objectClass=person)"
      username: mail
      idAttr: DN
      emailAttr: mail
      nameAttr: cn
Field                                 Type Description
noSimplePagination boolean Omit the Simple Paged Results control from the LDAP user and group synchronization searches.

Default: false

Notes

  • The noSimplePagination field is available starting with MKE 4.2.1. With earlier MKE 4k versions the field is accepted, however searches remain paginated.
  • The noSimplePagination setting applies to the user, group, and group member searches that MKE 4 runs to synchronize your directory. It requires the configuration of the userSearch setting.
  • Without pagination, the entire result set of a search is returned in a single response. As such, ensure that the size limit of your LDAP server is set to handle the number of entries in your directory, as otherwise the server will truncate the result.

To preserve simple pagination behavior when upgrading from MKE 3:

MKE 3 exposes the same setting as No Simple Pagination (RFC 2696) in the LDAP server settings, in the MKE 3 web UI under Admin Settings > Authentication & Authorization, and as noSimplePagination in the LDAP configuration of the MKE 3 API.

When you upgrade an MKE 3 cluster to MKE 4, the value of the MKE 3 setting is carried over to spec.authentication.ldap.noSimplePagination in the generated MKE 4 configuration. No manual action is required to preserve the behavior.

Configure LDAP using the MKE 4 Dashboard#

Important

Before LADP service users can use the MKE 4 Dashboard, it is first necessary to deploy additional ClusterRoleBindings. Refer to Grant sevice/proxy and Prometheus access for full details.

  1. Log in to the MKE 4 Dashboard as an administrator.

  2. In the left-side navigation panel, navigate to Admin Settings > Authentication.

  3. Select the LDAP tab.

  4. Tick enable LDAP.

  5. Enter the values that correspond with your LDAP server installation.

  6. Click the save settings button in the bottom right corner.