Skip to content

Commit 0d91d29

Browse files
jlhawnjoaofnfernandes
jlhawn
authored and
joaofnfernandes
committed
[datacenter/ucp] Improve LDAP directory docs (docker#1773)
Docker-DCO-1.1-Signed-off-by: Josh Hawn <[email protected]> (github: jlhawn)
1 parent cda96b5 commit 0d91d29

File tree

5 files changed

+134
-37
lines changed

5 files changed

+134
-37
lines changed

‎datacenter/ucp/2.1/guides/admin/configure/external-auth/index.md

+88-32
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,104 @@
11
---
2-
description: Learn how to integrate UCP with an LDAP service, so that you can manage
3-
users from a single place.
4-
keywords: LDAP, authentication, user management
5-
title: Integrate with LDAP
2+
description: Learn how to integrate UCP with an LDAP service, so that you can
3+
manage users from a single place.
4+
keywords: LDAP, directory, authentication, user management
5+
title: Integrate with an LDAP Directory
66
---
77

8-
Docker UCP integrates with LDAP services, so that you can manage users from a
9-
single place.
8+
Docker UCP integrates with LDAP directory services, so that you can manage
9+
users and groups from your organization's directory and it will automatically
10+
propagate that information to UCP and DTR.
1011

1112
## Configure the LDAP integration
1213

13-
To configure UCP to authenticate users using an LDAP service, go to
14-
the **UCP web UI**, navigate to the **Settings** page, and click the **Auth**
15-
tab.
14+
To configure UCP to create and authenticate users using an LDAP directory,
15+
go to the **UCP web UI**, navigate to the **Settings** page, and click the
16+
**Auth** tab.
1617

1718
![](../../../images/ldap-integration-1.png){: .with-border}
1819

19-
Then configure your LDAP integration.
20+
Then configure your LDAP directory integration.
2021

2122
**Authentication**
2223

2324
| Field | Description |
2425
|:-------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|
25-
| Method | The method used to authenticate users. Managed authentication uses the UCP built-in authentication mechanism. LDAP uses an LDAP service to authenticate users. |
26-
| Default permission for newly discovered accounts | The permission level assigned by default to a new user. Learn more about default permission levels. |
26+
| Method | The method used to create and authenticate users. The *LDAP* method uses a remote directory server to automatically create users and all logins will be forwarded to the directory server. |
27+
| Default permission for newly discovered accounts | The permission level assigned by default to a new user. [Learn more about default permission levels](../../manage-users/permission-levels.md). |
2728

2829
**LDAP server configuration**
2930

3031
| Field | Description |
3132
|:------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------|
3233
| LDAP server URL | The URL where the LDAP server can be reached. |
3334
| Recovery admin username | The username for a recovery user that can access UCP even when the integration with LDAP is misconfigured or the LDAP server is offline. |
34-
| Recovery admin password | The password for the recovery user. |
35+
| Recovery admin password | The password for the recovery user which is securely salted and hashed and stored in UCP. The recovery admin user can use this password to login if the LDAP server is misconfigured or offline. |
3536
| 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. |
3637
| Reader password | The password of the account used for searching entries in the LDAP server. |
3738

3839
**LDAP security options**
3940

40-
| Field | Description |
41-
|:----------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------|
42-
| Skip verification of server certificate | Whether to verify or not the LDAP server certificate when using TLS. The connection is still encrypted, but vulnerable to man-in-the-middle attacks. |
43-
| Use StartTLS | Whether to connect to the LDAP server using TLS or not. If you set the LDAP Server URL field with `ldaps://`, this field is ignored. |
41+
| Field | Description |
42+
|:----------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------|
43+
| Skip verification of server certificate | Whether to verify the LDAP server certificate when using TLS. The connection is still encrypted, but vulnerable to man-in-the-middle attacks. |
44+
| Use StartTLS | 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. |
4445

4546
**User search configurations**
4647

47-
| Field | Description |
48-
|:--------------------|:---------------------------------------------------------------------------------------------------------------------------------------|
49-
| Base DN | The distinguished name on the LDAP tree where the search should start looking for users. |
50-
| Username attribute | The LDAP attribute to use as username on UCP. |
51-
| Full name attribute | The LDAP attribute to use as user name on UCP. |
52-
| Filter | The LDAP search filter used to find LDAP users. If you leave this field empty, all LDAP entries on the Base DN, are imported as users. |
53-
| Search scope | 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. |
48+
| Field | Description |
49+
|:------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------|
50+
| Base DN | The distinguished name of the node in the directory tree where the search should start looking for users. |
51+
| Username attribute | The LDAP attribute to use as username on UCP. 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: `/` `\` `[` `]` `:` `;` `|` `=` `,` `+` `*` `?` `<` `>` `'` `"`. |
52+
| Full name attribute | The LDAP attribute to use as the user's full name for display purposes. If left empty, UCP will not create new users with a full name value. |
53+
| 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. |
54+
| Search scope | 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. |
55+
| 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. |
56+
| Iterate through group members | If `Match Group Members` is selected, this option searches for users by first iterating over the target group's membership and makes 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. |
57+
| Group DN | If `Match Group Members` is selected, this specifies the distinguished name of the group from which to select users. |
58+
| Group member attribute | If `Match Group Members` is selected, the value of this group attribute corresponds to the distinguished names of the members of the group. |
59+
60+
![](../../../images/ldap-integration-2.png){: .with-border}
61+
62+
Clicking **+ Add another user search configuration** will expand additional
63+
sections for configuring more user search queries. This is useful in cases
64+
where users may be found in multiple distinct subtrees of your organization's
65+
directory. Any user entry which matches at least one of the search
66+
configurations will be synced as a user.
5467

5568
**Advanced LDAP configuration**
5669

5770
| Field | Description |
5871
|:---------------------------|:----------------------------------------------------|
5972
| No simple pagination | If your LDAP server doesn't support pagination. |
6073
| Enable sync of admin users | Whether to import LDAP users as UCP administrators. |
74+
| LDAP Match Method | If admin user sync is enabled, this option specifies whether to match admin user entries using a search query or by selecting them as members from a group. For the expanded options, refer to the options described below. |
75+
76+
77+
**Match LDAP Group Members**
78+
79+
This option specifies that system admins should be synced directly with members
80+
of a group in your organization's LDAP directory. The admins will be synced to
81+
match the membership of the group. The configured recovery admin user will also
82+
remain a system admin.
83+
84+
| Field | Description |
85+
|:-----------------------|:------------------------------------------------------------------------------------------------------|
86+
| Group DN | This specifies the distinguished name of the group from which to select users. |
87+
| Group member attribute | The value of this group attribute corresponds to the distinguished names of the members of the group. |
88+
89+
**Match LDAP Search Results**
90+
91+
This option specifies that system admin should be synced using a search query
92+
against your organization's LDAP directory. The admins will by synced to match
93+
the users in the search results. The configured recovery admin user will also
94+
remain a system admin.
95+
96+
| Field | Description |
97+
|:--------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------|
98+
| Base DN | The distinguished name of the node in the directory tree where the search should start looking for users. |
99+
| Search scope | 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. |
100+
| Search Filter | The LDAP search filter used to find users. If you leave this field empty, all existing users in the search scope will be added as members of the team. |
101+
61102

62103
**Sync configuration**
63104

@@ -67,10 +108,10 @@ Then configure your LDAP integration.
67108

68109
**Test LDAP connection**
69110

70-
| Field | Description |
71-
|:-------------------|:---------------------------------------------------------------------|
72-
| LDAP test username | An LDAP user to test that the configuration is correctly configured. |
73-
| LDAP test password | The password of the LDAP user. |
111+
| Field | Description |
112+
|:---------|:-------------------------------------------------------------------------|
113+
| Username | The username with which the user will login to this application. This value should correspond to the Username Attribute specified in the form above. |
114+
| Password | The user's password used to authenticate (BIND) to the directory server. |
74115

75116
Before you save the configuration changes, you should test that the integration
76117
is correctly configured. You can do this by providing the credentials of an
@@ -79,15 +120,30 @@ LDAP user, and clicking the **Test** button.
79120
## Synchronize users
80121

81122
Once you've configure the LDAP integration, UCP synchronizes users based on the
82-
interval you've defined. When the synchronization runs, UCP stores logs that
83-
can help you troubleshoot when something goes wrong.
84-
123+
interval you've defined starting at the top of the hour. When the
124+
synchronization runs, UCP stores logs that can help you troubleshoot when
125+
something goes wrong.
85126

86127
You can also manually synchronize users by clicking the **Sync Now** button.
87128

88129
## Revoke user access
89130

90131
When a user is removed from LDAP, that user becomes inactive after the LDAP
91132
synchronization runs.
133+
92134
Also, when you switch from the built-in authentication to using LDAP
93-
authentication, all manually created users become inactive.
135+
authentication, all manually created users whose usernames do not match any
136+
LDAP search results become inactive with the exception of the recovery admin
137+
user which can still login with the recovery admin password.
138+
139+
## Data synced from your organization's LDAP directory
140+
141+
UCP saves a minimum amount of user data required to operate. This includes
142+
the value of the username and full name attributes that you have specified in
143+
the configuration as well as the distinguished name of each synced user.
144+
UCP does not query, or store any additional data from the directory server.
145+
146+
## Syncing Teams
147+
148+
For syncing teams in UCP with a search query or group in your organization's
149+
LDAP directory, refer to [the documentation on creating and managing teams](../../manage-users/create-and-manage-teams.md).

‎datacenter/ucp/2.1/guides/admin/manage-users/create-and-manage-teams.md

+44-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
description: Learn how to create and manage user permissions, using teams in your
3-
Docker Universal Control Plane cluster.
4-
keywords: authorize, authentication, users, teams, UCP, Docker
2+
description: Learn how to create and manage user permissions, using teams in
3+
your Docker Universal Control Plane cluster.
4+
keywords: authorize, authentication, users, teams, groups, sync, UCP, Docker
55
title: Create and manage teams
66
---
77

@@ -28,6 +28,47 @@ Then choose the list of users that you want to add to the team.
2828

2929
![](../../images/create-and-manage-teams-3.png){: .with-border}
3030

31+
## Sync team members with your organization's LDAP directory.
32+
33+
If UCP is configured to sync users with your organization's LDAP directory
34+
server, you will have the option to enable syncing the new team's members when
35+
creating a new team or when modifying settings of an existing team.
36+
[Learn how to configure integration with an LDAP directory](../configure/external-auth/index.md).
37+
Enabling this option will expand the form with additional field for configuring
38+
the sync of team members.
39+
40+
![](../../images/create-and-manage-teams-5.png){: .with-border}
41+
42+
There are two methods for matching group members from an LDAP directory:
43+
44+
**Match LDAP Group Members**
45+
46+
This option specifies that team members should be synced directly with members
47+
of a group in your organization's LDAP directory. The team's membership will by
48+
synced to match the membership of the group.
49+
50+
| Field | Description |
51+
|:-----------------------|:------------------------------------------------------------------------------------------------------|
52+
| Group DN | This specifies the distinguished name of the group from which to select users. |
53+
| Group member attribute | The value of this group attribute corresponds to the distinguished names of the members of the group. |
54+
55+
**Match LDAP Search Results**
56+
57+
This option specifies that team members should be synced using a search query
58+
against your organization's LDAP directory. The team's membership will be
59+
synced to match the users in the search results.
60+
61+
| Field | Description |
62+
|:--------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------|
63+
| Base DN | The distinguished name of the node in the directory tree where the search should start looking for users. |
64+
| Search scope | 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. |
65+
| Search Filter | The LDAP search filter used to find users. If you leave this field empty, all existing users in the search scope will be added as members of the team. |
66+
67+
**Immediately Sync Team Members**
68+
69+
Select this option to immediately run an LDAP sync operation after saving the
70+
configuration for the team. It may take a moment before the members of the team
71+
are fully synced.
3172

3273
## Manage team permissions
3374

‎datacenter/ucp/2.1/guides/admin/manage-users/permission-levels.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
description: Learn about the permission levels available in Docker Universal Control
3-
Plane.
2+
description: Learn about the permission levels available in Docker Universal
3+
Control Plane.
44
keywords: authorization, authentication, users, teams, UCP
55
title: Permission levels
66
---

‎datacenter/ucp/2.1/guides/images/create-and-manage-teams-5.png

36 KB
Loading

‎datacenter/ucp/2.1/guides/images/ldap-integration-2.png

36.9 KB
Loading

0 commit comments

Comments
 (0)