Configure the LDAP integration

Note

MKE saves a minimum amount of user data required to operate, including any user name and full name attributes that you specify in the configuration, as well as the Distinguished Name (DN) of each synced user. MKE does not store any other data from the directory server.

Use the MKE web UI to configure MKE to create and authenticate users using an LDAP directory.

Access the LDAP controls

To configure LDAP integration you must first gain access to the controls for the service protocol.

  1. Log in to the MKE web UI.

  2. In the left-side navigation menu, click the user name drop-down to display the available options.

  3. Navigate to Admin Settings > Authentication & Authorization.

  4. In the Identity Provider section in the details pane, move the slider next to LDAP to enable the LDAP settings.

Set up an LDAP server

To configure an LDAP server, perform the following steps:

  1. To set up a new LDAP server, configure the settings in the LDAP Server subsection:

    Control

    Description

    LDAP Server URL

    The URL for the LDAP server.

    Reader DN

    The DN of the LDAP account that is used to search entries in the LDAP server. As a best practice, this should be an LDAP read-only user.

    Reader Password

    The password of the account used to search entries in the LDAP server.

    Skip TLS verification

    Sets whether to verify the LDAP server certificate when TLS is in use. The connection is still encrypted, however it is vulnerable to man-in-the-middle attacks.

    Use Start TLS

    Defines whether to authenticate or encrypt the connection after connection is made to the LDAP server over TCP. To ignore the setting, set the LDAP Server URL field to ldaps://.

    No Simple Pagination (RFC 2696)

    Indicates that your LDAP server does not support pagination.

    Just-In-Time User Provisioning

    Sets whether to create user accounts only when users log in for the first time. Mirantis recommends using the default true value.

    Note

    Available as of MKE 3.6.4 The disableReferralChasing setting, which is currently only available by way of the MKE API, allows you to disable the default behavior that occurs when a referral URL is received as a result of an LDAP search request. Refer to LDAP Configuration through API for more information.

  2. Click Save to add your LDAP server.

Add additional LDAP domains

To integrate MKE with additional LDAP domains:

  1. In the LDAP Additional Domains subsection, click Add LDAP Domain +. A set of input tools for configuring the additional domain displays.

  2. Configure the settings for the new LDAP domain:

    Control

    Description

    LDAP Domain

    Text field in which to enter the root domain component of this server. A longest-suffix match of the Base DN for LDAP searches is used to select which LDAP server to use for search requests. If no matching domain is found, the default LDAP server configuration is put to use.

    LDAP Server URL

    Text field in which to enter the URL for the LDAP server.

    Reader DN

    Text field in which to enter the DN of the LDAP account that is used to search entries in the LDAP server. As a best practice, this should be an LDAP read-only user.

    Reader Password

    The password of the account used to search entries in the LDAP server.

    Skip TLS verification

    Sets whether to verify the LDAP server certificate when TLS is in use. The connection is still encrypted, however it is vulnerable to man-in-the-middle attacks.

    Use Start TLS

    Sets whether to authenticate or encrypt the connection after connection is made to the LDAP server over TCP. To ignore the setting, set the LDAP Server URL field to ldaps://.

    No Simple Pagination (RFC 2696)

    Select if your LDAP server does not support pagination.

    Note

    Available as of MKE 3.6.4 The disableReferralChasing setting, which is currently only available by way of the MKE API, allows you to disable the default behavior that occurs when a referral URL is received as a result of an LDAP search request. Refer to LDAP Configuration through API for more information.

  3. Click Confirm to add the new LDAP domain.

  4. Repeat the procedure to add any additional LDAP domains.

Add LDAP user search configurations

To add LDAP user search configurations to your LDAP integration:

  1. In the LDAP User Search Configurations subsection, click Add LDAP User Search Configuration +.A set of input tools for configuring the LDAP user search configurations displays.

    Field

    Description

    Base DN

    Text field in which to enter the DN of the node in the directory tree, where the search should begin seeking out users.

    Username Attribute

    Text field in which to enter the LDAP attribute that serves as username on MKE. Only user entries with a valid username will be created.

    A valid username must not be longer than 100 characters and must not contain any unprintable characters, whitespace characters, or any of the following characters: / \ [ ] : ; | = , + * ? < > ' ".

    Full Name Attribute

    Text field in which to enter the LDAP attribute that serves as the user’s full name, for display purposes. If the field is left empty, MKE does not create new users with a full name value.

    Filter

    Text field in which to enter an LDAP search filter to use to find users. If the field is left empty, all directory entries in the search scope with valid username attributes are created as users.

    Search subtree instead of just one level

    Whether to perform the LDAP search on a single level of the LDAP tree, or search through the full LDAP tree starting at the Base DN.

    Match Group Members

    Sets whether to filter users further, by selecting those who are also members of a specific group on the directory server. The feature is helpful when the LDAP server does not support memberOf search filters.

    Iterate through group members

    Sets whether, when the Match Group Members option is enabled to sync users, the sync is done by iterating over the target group’s membership and making a separate LDAP query for each member, rather than through the use of a broad user search filter. This option can increase efficiency in situations where the number of members of the target group is significantly smaller than the number of users that would match the above search filter, or if your directory server does not support simple pagination of search results.

    Group DN

    Text field in which to enter the DN of the LDAP group from which to select users, when the Match Group Members option is enabled.

    Group Member Attribute

    Text field in which to enter the name of the LDAP group entry attribute that corresponds to the DN of each of the group members.

  2. Click Confirm to add the new LDAP user search configurations.

  3. Repeat the procedure to add any additional user search configurations. More than one such configuration can be useful in cases where users may be found in multiple distinct subtrees of your organization directory. Any user entry that matches at least one of the search configurations will be synced as a user.

Test LDAP login

Prior to saving your configuration changes, you can use the dedicated LDAP Test login tool to test the integration using the login credentials of an LDAP user.

  1. Input the credentials for the test user into the provided Username and Passworfd fields:

    Field

    Description

    Username

    An LDAP user name for testing authentication to MKE. The value corresponds to the Username Attribute that is specified in the Add LDAP user search configurations section.

    Password

    The password used to authenticate (BIND) to the directory server.

  2. Click Test. A search is made against the directory using the provided search Base DN, scope, and filter. Once the user entry is found in the directory, a BIND request is made using the input user DN and the given password value.

Set LDAP synchronization

Following LDAP integration, MKE synchronizes users at the top of the hour, based on an intervial that is defined in hours.

To set LDAP synchronization, configure the following settings in the LDAP Sync Configuration section:

Field

Description

Sync interval

The interval, in hours, to synchronize users between MKE and the LDAP server. When the synchronization job runs, new users found in the LDAP server are created in MKE with the default permission level. MKE users that do not exist in the LDAP server become inactive.

Enable sync of admin users

This option specifies that system admins should be synced directly with members of a group in your organization’s LDAP directory. The admins will be synced to match the membership of the group. The configured recovery admin user will also remain a system admin.

Manually synchronize LDAP

In addition to configuring MKE LDAP synchronization, you can also perform a hot synchronization by clicking the Sync Now button in the LDAP Sync Jobs subsection. Here you can also view the logs for each sync jobs by clicking View Logs link associated with a particular job.

Revoke user access

Whenever a user is removed from LDAP, the effect on their MKE account is determined by the Just-In-Time User Provisioning setting:

  • false: Users deleted from LDAP become inactive in MKE following the next LDAP synchronization runs.

  • true: A user deleted from LDAP cannot authenticate. Their MKE accounts remain active, however, and thus they can use their client bundles to run commands. To prevent this, deactivate the user’s MKE user account.

Synchronize teams with LDAP

MKE enables the syncing of teams within Organizations with LDAP, using either a search query or by matching a group that is established in your LDAP directory.

  1. Log in to the MKE web UI as an administrator.

  2. Navigate to Access Control > Orgs & Teams to display the Organizations that exist within your MKE instance.

  3. Locate the name of the Organization that contains the MKE team that you want to sync to LDAP and click it to display all of the MKE teams for that Organization.

  4. Hover your cursor over the MKE team that you want to sync with LDAP to reveal its vertical ellipsis, at the far right.

  5. Click the vertical ellipsis and select Edit to call the Details screen for the team.

  6. Toggle ENABLE SYNC TEAM MEMBERS to Yes to reveal the LDAP sync controls.

  7. Toggle LDAP MATCH METHOD to set the LDAP match method you want to use to make the sync, Match Search Results (default) or Match Group Members.

    • For Match Search Results:

      1. Enter a Base DN into the Search Base DN field, as it is established in LDAP.

      2. Enter a search filter based on one or more attributes into the Search filter field.

      3. Optional. Check Search subtree instead of just one level to enable search down through any sub-groups that exist within the group you entered into the Search Base DN field.

    • For Match Group Members:

      1. Enter the group Distinguised Name (DN) into the Group DN field.

      2. Enter a member attribute into the Group Member field.

  8. Toggle IMMEDIATELY SYNC TEAM MEMBERS as appropriate.

  9. Toggle ALLOW NON-LDAP MEMBERS as appropriate.

  10. Click Save.

LDAP Configuration through API

LDAP-specific GET and PUT API endpoints are available in the configuration resource. Swarm mode must be enabled to use the following endpoints:

  • GET /api/ucp/config/auth/ldap - Returns information on your current system LDAP configuration.

  • PUT /api/ucp/config/auth/ldap - Updates your LDAP configuration.