MKE integrates with LDAP directory services, so that you can manage users and groups from your organization’s directory and it will automatically propagate that information to MKE and MSR.
If you enable LDAP, MKE uses a remote directory server to create users automatically, and all logins are forwarded to the directory server.
When you switch from built-in authentication to LDAP authentication, all manually created users whose usernames don’t match any LDAP search results are still available.
When you enable LDAP authentication, you can choose whether MKE creates user accounts only when users log in for the first time. Select the Just-In-Time User Provisioning option to ensure that the only LDAP accounts that exist in MKE are those that have had a user log in to MKE.
You control how MKE integrates with LDAP by creating searches for users.
You can specify multiple search configurations, and you can specify
multiple LDAP servers to integrate with. Searches start with the
Base DN
, which is the distinguished name of the node in the LDAP
directory tree where the search starts looking for users.
Access LDAP settings by navigating to the Authentication & Authorization page in the MKE web interface. There are two sections for controlling LDAP searches and servers.
Base DN
, scope
, filter
, the username
attribute, and the full name
attribute. These searches are stored
in a list, and the ordering may be important, depending on your
search configuration.Here’s what happens when MKE synchronizes with LDAP:
Base DN
from the user search config and selecting
the domain server that has the longest domain suffix match.Base DN
from the search config, MKE uses the default domain server.The domain server to use is determined by the Base DN
in each search
config. MKE doesn’t perform search requests against each of the domain
servers, only the one which has the longest matching domain suffix, or
the default if there’s no match.
Here’s an example. Let’s say we have three LDAP domain servers:
Domain | Server URL |
---|---|
default | ldaps://ldap.example.com |
dc=subsidiary1,dc=com |
ldaps://ldap.subsidiary1.com |
dc=subsidiary2,dc=subsidiary1,dc=com |
ldaps://ldap.subsidiary2.com |
Here are three user search configs with the following Base DNs
:
baseDN=ou=people,dc=subsidiary1,dc=com
For this search config, dc=subsidiary1,dc=com
is the only server
with a domain which is a suffix, so MKE uses the server
ldaps://ldap.subsidiary1.com
for the search request.
baseDN=ou=product,dc=subsidiary2,dc=subsidiary1,dc=com
For this search config, two of the domain servers have a domain which
is a suffix of this base DN, but
dc=subsidiary2,dc=subsidiary1,dc=com
is the longer of the two, so
MKE uses the server ldaps://ldap.subsidiary2.com
for the search
request.
baseDN=ou=eng,dc=example,dc=com
For this search config, there is no server with a domain specified
which is a suffix of this base DN, so MKE uses the default server,
ldaps://ldap.example.com
, for the search request.
If there are username
collisions for the search results between
domains, MKE uses only the first search result, so the ordering of the
user search configs may be important. For example, if both the first and
third user search configs result in a record with the username
jane.doe
, the first has higher precedence and the second is ignored.
For this reason, it’s important to choose a username
attribute
that’s unique for your users across all domains.
Because names may collide, it’s a good idea to use something unique to
the subsidiary, like the email address for each person. Users can log in
with the email address, for example, jane.doe@subsidiary1.com
.
To configure MKE to create and authenticate users by using an LDAP directory, go to the MKE web interface, navigate to the Admin Settings page, and click Authentication & Authorization to select the method used to create and authenticate users.
In the LDAP Enabled section, click Yes. Now configure your LDAP directory integration.
Use this setting to change the default permissions of new users.
Click the drop-down menu to select the permission level that MKE assigns
by default to the private collections of new users. For example, if you
change the value to View Only
, all users who log in for the first
time after the setting is changed have View Only
access to their
private collections, but permissions remain unchanged for all existing
users.
Click Yes to enable integrating MKE users and teams with LDAP servers.
Field | Description |
---|---|
LDAP server URL | The URL where the LDAP server can be reached. |
Reader DN | The distinguished name of the LDAP account used for searching 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 for searching entries in the LDAP server. |
Use Start TLS | Whether to authenticate/encrypt the connection after connecting to the
LDAP server over TCP. If you set the LDAP Server URL field with
ldaps:// , this field is ignored. |
Skip TLS verification | Whether to verify the LDAP server certificate when using TLS. The connection is still encrypted but vulnerable to man-in-the-middle attacks. |
No simple pagination | If your LDAP server doesn’t support pagination. |
Just-In-Time User Provisioning | Whether to create user accounts only when users log in for the first
time. The default value of true is recommended. If you upgraded from
UCP 2.0.x, the default is false . |
Note
LDAP connections using certificates created with TLS v1.2 do not currently advertise support for sha512WithRSAEncryption in the TLS handshake which leads to issues establishing connections with some clients. Support for advertising sha512WithRSAEncryption will be added in MKE 3.1.0.
Click Confirm to add your LDAP domain.
To integrate with more LDAP servers, click Add LDAP Domain.
Field | Description |
---|---|
Base DN | The distinguished name of the node in the directory tree where the search should start looking for users. |
Username attribute | The LDAP attribute to use as username on MKE. Only user entries with a
valid username will be created. A valid username is no longer than 100
characters and does not contain any unprintable characters, whitespace
characters, or any of the following characters: / \ [ ]
: ; | = , + * ? < > ' ,
" . |
Full name attribute | The LDAP attribute to use as the user’s full name for display purposes. If left empty, MKE will not create new users with a full name value. |
Filter | The LDAP search filter used to find users. If you leave this field 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 | Whether to further filter users by selecting those who are also members
of a specific group on the directory server. This feature is helpful if
the LDAP server does not support memberOf search filters. |
Iterate through group members | If Select Group Members is selected, this option searches for users
by first iterating over the target group’s membership, making a separate
LDAP query for each member, as opposed to first querying for all users
which match the above search query and intersecting those with the set
of group members. This option can be more efficient in situations where
the number of members of the target group is significantly smaller than
the number of users which would match the above search filter, or if
your directory server does not support simple pagination of search
results. |
Group DN | If Select Group Members is selected, this specifies the
distinguished name of the group from which to select users. |
Group Member Attribute | If Select Group Members is selected, the value of this group
attribute corresponds to the distinguished names of the members of the
group. |
To configure more user search queries, click Add LDAP User Search Configuration again. This is useful in cases where users may be found in multiple distinct subtrees of your organization’s directory. Any user entry which matches at least one of the search configurations will be synced as a user.
Field | Description |
---|---|
Username | An LDAP username for testing authentication to this application. This value corresponds with the Username Attribute specified in the LDAP user search configurations section. |
Password | The user’s password used to authenticate (BIND) to the directory server. |
Before you save the configuration changes, you should test that the integration is correctly configured. You can do this by providing the credentials of an LDAP user, and clicking the Test button.
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 don’t 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. |
Once you’ve configured the LDAP integration, MKE synchronizes users based on the interval you’ve defined starting at the top of the hour. When the synchronization runs, MKE stores logs that can help you troubleshoot when something goes wrong.
You can also manually synchronize users by clicking Sync Now.
When a user is removed from LDAP, the effect on the user’s MKE account depends on the Just-In-Time User Provisioning setting:
false
: Users deleted from
LDAP become inactive in MKE after the next LDAP synchronization runs.true
: Users deleted from
LDAP can’t authenticate, but their MKE accounts remain active. This
means that they can use their client bundles to run commands. To
prevent this, deactivate their MKE user accounts.MKE saves a minimum amount of user data required to operate. This includes the value of the username and full name attributes that you have specified in the configuration as well as the distinguished name of each synced user. MKE does not store any additional data from the directory server.
MKE enables syncing teams with a search query or group in your organization’s LDAP directory.
As of MKE 3.1.5, LDAP-specific GET
and PUT
API endpoints have
been added to the Config resource. Note that swarm mode has to be
enabled before you can hit the following endpoints:
GET /api/ucp/config/auth/ldap
- Returns information on your
current system LDAP configuration.PUT /api/ucp/config/auth/ldap
- Lets you update your LDAP
configuration.