Skip to content

Commit 50afcdd

Browse files
themr0cthemr0c
committed
RHIDP-7612 Added _Enablig user provisioning with LDAP_
Signed-off-by: Fabrice Flore-Thébault <[email protected]>
1 parent 6b8b397 commit 50afcdd

File tree

2 files changed

+356
-0
lines changed

2 files changed

+356
-0
lines changed

‎assemblies/assembly-authenticating-with-rhbk.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,7 @@
77
include::modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc[leveloffset=+1]
88

99

10+
include::modules/authentication/proc-enabling-user-provisioning-with-ldap.adoc[leveloffset=+1]
11+
12+
1013
include::modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc[leveloffset=+1]

‎modules/authentication/proc-enabling-user-provisioning-with-ldap.adoc‎

Lines changed: 353 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,353 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="enabling-user-provisioning-with-ldap"]
4+
= Enabling user provisioning with LDAP
5+
6+
Provision users and groups from Lightweight Directory Access Protocol (LDAP) to the {product} software catalog, rather than using authentication provider in {product-short}.
7+
8+
.Prerequisites
9+
* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
10+
11+
* You have configured xref:assembly-authenticating-with-rhbk[authentication with {rhbk-brand-name} ({rhbk})].
12+
13+
* You have collected the required LDAP credentials:
14+
15+
LDAP URL::
16+
Your LDAP server URL, such as `ldaps://ds.example.net`.
17+
18+
Bind dn::
19+
Your bind distinguished name, such as `cn=admin,OU=Users,DC=rhdh,DC=test`
20+
21+
LDAP secret::
22+
Your LDAP secret.
23+
24+
Recommended: LDAP certificates and keys::
25+
Your LDAP certificates and keys, when using a secure LDAP connexion (`ldaps://`).
26+
27+
28+
.Procedure
29+
. Enter your LDAP credentials to {product-short}, by adding the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets].
30+
You can use these secrets in the {product-short} configuration files by using their respective environment variable name.
31+
32+
`LDAP_SECRET`::
33+
Enter your LDAP secret.
34+
35+
. Recommended: To use a secure LDAP connection (`ldaps://`), add your LDAP certificates and keys files to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets].
36+
37+
`ldap_certs`::
38+
39+
`ldap_keys`::
40+
41+
. Enable the LDAP organization provisioning plugin (`backstage-plugin-catalog-backend-module-ldap`).
42+
This plugin ingests LDAP users and groups to the {product-short} software catalog.
43+
+
44+
.`dynamic-plugins.yaml` file fragment
45+
[source,yaml]
46+
----
47+
plugins:
48+
- package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-ldap'
49+
disabled: false
50+
----
51+
52+
. Enable provisioning GitHub users and groups to the {product-short} software catalog, by adding the `catalog.providers.ldapOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
53+
54+
.. Optional: Consider removing other catalog provider, by removing other catalog provider section.
55+
56+
.. Enter the mandatory fields:
57+
+
58+
[source,yaml]
59+
----
60+
catalog:
61+
providers:
62+
ldapOrg:
63+
default:
64+
target: ldaps://ds.example.net
65+
bind:
66+
dn: cn=admin,ou=Users,dc=rhdh
67+
secret: ${LDAP_SECRET}
68+
users:
69+
- dn: OU=Users,OU=RHDH Local,DC=rhdh,DC=test
70+
options:
71+
filter: (uid=*)
72+
groups:
73+
- dn: OU=Groups,OU=RHDH Local,DC=rhdh,DC=test
74+
schedule:
75+
frequency: PT1H
76+
timeout: PT15M
77+
----
78+
79+
`target`::
80+
Enter your LDAP server URL, such as `ldaps://ds.example.net`.
81+
82+
`bind`::
83+
Enter your service account informations:
84+
85+
`dn`:::
86+
Enter your service account distinguished name (DN), such as `cn=admin,OU=Users,DC=rhdh,DC=test`
87+
88+
`secret`:::
89+
Enter the name of the variable containing your LDAP secret: `${LDAP_SECRET}`.
90+
91+
`users`::
92+
Enter information about how to find your users:
93+
94+
`dn`:::
95+
Enter the DN containing the user information.
96+
97+
`options`:::
98+
99+
`filter`::::
100+
Enter your filter, such as `(uid=*)` to provision to the {product-very-short} software catalog only users with a valid `uid`.
101+
102+
`groups`::
103+
Enter information about how to find your groups:
104+
105+
`dn`:::
106+
Enter the DN containing the group information.
107+
108+
`schedule`::
109+
Enter your schedule information:
110+
111+
`frequency`:::
112+
Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.
113+
114+
`timeout`:::
115+
Enter your schedule timeout, in the ISO duration or "human duration" format.
116+
117+
`initialDelay`:::
118+
Enter your schedule initial delay, in the ISO duration or "human duration" format.
119+
120+
.. Optional: To change how {product-short} maps LDAP user fields to the software catalog, enter optional `maps` and `set` fields.
121+
+
122+
[source,yaml]
123+
----
124+
catalog:
125+
providers:
126+
ldapOrg:
127+
default:
128+
target: ldaps://ds.example.net
129+
bind:
130+
dn: cn=admin,ou=Users,dc=rhdh
131+
secret: ${LDAP_SECRET}
132+
users:
133+
- dn: OU=Users,OU=RHDH Local,DC=rhdh,DC=test
134+
options:
135+
filter: (uid=*)
136+
map:
137+
rdn: uid
138+
name: uid
139+
description: {}
140+
displayName: cn
141+
email: mail
142+
picture: {}
143+
memberOf: memberOf
144+
set:
145+
metadata.customField: 'hello'
146+
groups:
147+
- dn: OU=Groups,OU=RHDH Local,DC=rhdh,DC=test
148+
schedule:
149+
frequency: PT1H
150+
timeout: PT15M
151+
----
152+
153+
`rdn`::
154+
To change the default value: `uid`, enter the relative distinguished name of each entry.
155+
156+
`name`::
157+
To change the default value: `uid`, enter the LDAP field to map to the {product-very-short} `metadata.name` field.
158+
159+
`description`::
160+
To set a value, enter the LDAP field to map to the {product-very-short} `metadata.description` field.
161+
162+
`displayName`::
163+
To change the default value: `cn`, enter the LDAP field to map to the {product-very-short} `metadata.displayName` field.
164+
165+
`email`::
166+
To change the default value: `mail`, enter the LDAP field to map to the {product-very-short} `spec.profile.email` field.
167+
168+
`picture`::
169+
To set a value, enter the LDAP field to map to the {product-very-short} `spec.profile.picture` field.
170+
171+
`memberOf`::
172+
To change the default value: `memberOf`, enter the LDAP field to map to the {product-very-short} `spec.memberOf` field.
173+
174+
`set`::
175+
To set a value, enter the hard coded JSON to apply to the entities after ingestion, such as `metadata.customField: 'hello'`.
176+
177+
.. Optional: To change how {product-short} maps LDAP group fields to the software catalog, enter optional `groups.maps` fields.
178+
+
179+
[source,yaml]
180+
----
181+
catalog:
182+
providers:
183+
ldapOrg:
184+
default:
185+
target: ldaps://ds.example.net
186+
bind:
187+
dn: cn=admin,ou=Users,dc=rhdh
188+
secret: ${LDAP_SECRET}
189+
users:
190+
- dn: OU=Users,OU=RHDH Local,DC=rhdh,DC=test
191+
options:
192+
filter: (uid=*)
193+
groups:
194+
- dn: OU=Groups,OU=RHDH Local,DC=rhdh,DC=test
195+
map:
196+
rdn: uid
197+
name: uid
198+
description: {}
199+
displayName: cn
200+
email: mail
201+
picture: {}
202+
memberOf: memberOf
203+
members: member
204+
type: groupType
205+
set:
206+
metadata.customField: 'hello'
207+
schedule:
208+
frequency: PT1H
209+
timeout: PT15M
210+
----
211+
212+
`rdn`::
213+
To change the default value: `cn`, enter the relative distinguished name of each entry.
214+
215+
`name`::
216+
To change the default value: `cn`, enter the LDAP field to map to the {product-very-short} `metadata.name` field.
217+
218+
`description`::
219+
To set a value, enter the LDAP field to map to the {product-very-short} `metadata.description` field.
220+
221+
`displayName`::
222+
To change the default value: `cn`, enter the LDAP field to map to the {product-very-short} `metadata.displayName` field.
223+
224+
`email`::
225+
To change the default value: `mail`, enter the LDAP field to map to the {product-very-short} `spec.profile.email` field.
226+
227+
`picture`::
228+
To set a value, enter the LDAP field to map to the {product-very-short} `spec.profile.picture` field.
229+
230+
`memberOf`::
231+
To change the default value: `memberOf`, enter the LDAP field to map to the {product-very-short} `spec.memberOf` field.
232+
233+
`members`::
234+
To change the default value: `member`, enter the LDAP field to map to the {product-very-short} `spec.children` field.
235+
236+
`type`::
237+
To change the default value: `groupType`, enter the LDAP field to map to the {product-very-short} `spec.type` field.
238+
239+
`set`::
240+
To set a value, enter the hard coded JSON to apply to the entities after ingestion, such as `metadata.customField: 'hello'`.
241+
242+
.. Recommended: To use a secure LDAP connection (`ldaps://`), enter optional `tls` fields.
243+
+
244+
.Optional `tls` fields
245+
[source,yaml]
246+
----
247+
catalog:
248+
providers:
249+
ldapOrg:
250+
default:
251+
target: ldaps://ds.example.net
252+
bind:
253+
dn: cn=admin,ou=Users,dc=rhdh
254+
secret: ${LDAP_SECRET}
255+
users:
256+
ldapOrg:
257+
default:
258+
tls:
259+
rejectUnauthorized: true
260+
keys: '/path/to/keys.pem'
261+
certs: '/path/to/certs.pem'
262+
----
263+
264+
`rejectUnauthorized`::
265+
Set to `false` to allow self-signed certificates
266+
+
267+
WARNING: This option is not recommended for production.
268+
269+
`keys`::
270+
Enter a file containing private keys in PEM format
271+
272+
`certs`::
273+
Enter a file containing cert chains in PEM format
274+
275+
.. Optional: Enter configuration for vendor-specific attributes to set custom attribute names for distinguished names (DN) and universally unique identifiers (UUID) in LDAP directories.
276+
Default values are defined per supported vendor and automatically detected.
277+
+
278+
[source,yaml]
279+
----
280+
catalog:
281+
providers:
282+
ldapOrg:
283+
default:
284+
vendor:
285+
dnAttributeName: customDN
286+
uuidAttributeName: customUUID
287+
----
288+
289+
`dnAttributeName`::
290+
Enter the attribute name that holds the distinguished name (DN) for an entry.
291+
292+
`uuidAttributeName`::
293+
Enter the attribute name that holds a universal unique identifier (UUID) for an entry.
294+
295+
.. Optional: Enter low level users and groups configuration in the `options` subsection.
296+
+
297+
[source,yaml]
298+
----
299+
catalog:
300+
providers:
301+
ldapOrg:
302+
default:
303+
target: ldaps://ds.example.net
304+
bind:
305+
dn: cn=admin,ou=Users,dc=rhdh
306+
secret: ${LDAP_SECRET}
307+
users:
308+
options:
309+
scope: sub
310+
filter: (uid=*)
311+
attributes:
312+
- cn
313+
- uid
314+
- description
315+
paged:
316+
pageSize: 500
317+
groups:
318+
options:
319+
scope: sub
320+
filter: (cn=*)
321+
attributes:
322+
- cn
323+
- uid
324+
- description
325+
paged:
326+
pageSize: 500
327+
----
328+
329+
`scope`::
330+
To change the default value: `one`, enter how deep the search should go within the directory tree:
331+
* `base` to search only the base DN.
332+
* `one` to search one level below the base DN.
333+
* `sub` to search all descendant entries.
334+
335+
`filter`::
336+
To change the default value: `(objectclass=*)`, enter your LDAP filter.
337+
With the default mapping:
338+
* For users, enter `(uid=*)` to make sure only users with valid uid field is synced, since users without uid will cause error and ingestion fails.
339+
* For groups, enter `(cn=*)`
340+
+
341+
[TIP]
342+
====
343+
When you change the mapping, also update the filter.
344+
====
345+
346+
.Verification
347+
* To verify user and group provisioning, check the console logs.
348+
+
349+
.Successful synchronization example:
350+
[source,json]
351+
----
352+
353+
----

0 commit comments

Comments
 (0)