RHIDP-7612 Added _Enablig user provisioning with LDAP_

assemblies/assembly-authenticating-with-rhbk.adoc

@@ -5,4 +5,7 @@
 include::modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc[leveloffset=+1]
 
 
+include::modules/authentication/proc-enabling-user-provisioning-with-ldap.adoc[leveloffset=+1]
+
+
 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

@@ -0,0 +1,198 @@
+[id="enabling-user-provisioning-with-ldap"]
+= Enabling user provisioning with LDAP
+
+When your identity provider is LDAP, consider provision the users and groups from LDAP to the {product-short} software catalog, rather than using the provider usually bound to your authentication provider.
+
+.Prerequisites
+* You link:{configuring-book-url}[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
+
+* You have collected the required LDAP credentials:
+
+LDAP URL::
+Your LDAP server URL, such as `ldaps://ds.example.net`.
+
+Bind dn::
+Your bind distinguished name, such as `cn=admin,OU=Users,DC=rhdh,DC=test`
+
+LDAP secret::
+Your LDAP secret.
+
+* You have configured authentication with your external authentication provider.
+
+.Procedure
+. To add your LDAP credentials to {product-short}, add the following key/value pairs to link:{configuring-dynamic-plugins-book-url}#provisioning-your-custom-configuration[your {product-short} secrets].
+You can use these secrets in the {product-short} configuration files by using their respective environment variable name.
+
+`LDAP_SECRET`::
+Enter your LDAP secret.
+
+. Enable the LDAP organization provisioning plugin (`backstage-plugin-catalog-backend-module-ldap`).
+This plugin ingests LDAP users and groups to the {product-short} software catalog.
++
+.`dynamic-plugins.yaml` file fragment
+[source,yaml]
+----
+plugins:
+  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-ldap'
+    disabled: false
+----
+
+. To provision GitHub users and groups to the {product-short} software catalog, add the `catalog.providers.ldapOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
+
+.. Optional: Consider removing any other
+
+.. Enter the mandatory fields:
++
+[id=ldapOrg]
+.`{my-app-config-file}` fragment with mandatory `catalog.providers.ldapOrg` fields
+[source,yaml]
+----
+catalog:
+  providers:
+    ldapOrg:
+      default:
+        target: ldaps://ds.example.net
+        bind:
+          dn: cn=admin,ou=Users,dc=rhdh
+          secret: ${LDAP_SECRET}
+        users:
+          - dn: OU=Users,OU=RHDH Local,DC=rhdh,DC=test
+            options:
+              filter: (uid=*)
+        groups:
+          - dn: OU=Groups,OU=RHDH Local,DC=rhdh,DC=test
+        schedule:
+          frequency: PT1H
+          timeout: PT15M
+----
+
+target::
+Your LDAP server URL, such as `ldaps://ds.example.net`.
+
+bind::
+
+dn:::
+Enter the distinguished name (DN) of your service account, such as `cn=admin,OU=Users,DC=rhdh,DC=test`
+
+secret:::
+Enter the name of the variable containing your LDAP secret: `${LDAP_SECRET}`.
+
+users::
+
+dn:::
+Enter the DN containing the user information.
+
+options:::
+
+filter::::
+Enter your filter, such as `(uid=*)` to provision to the {product-very-short} software catalog only users with a valid `uid`.
+
+groups::
+
+dn:::
+Enter the DN containing the group information.
+
+`schedule.frequency`::
+Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.
+
+`schedule.timeout`::
+Enter your schedule timeout, in the ISO duration or "human duration" format.
+
+`schedule.initialDelay`::
+Enter your schedule initial delay, in the ISO duration or "human duration" format.
+
+.. Optional: Enter optional `users` fields:
+
+map::
+
+rdn:::
+To change the default value: `uid`, enter the relative distinguished name of each entry.
+
+name:::
+To change the default value: `uid`, enter the LDAP field to map to the {product-very-short} `metadata.name` field.
+
+description:::
+To set a value, enter the LDAP field to map to the {product-very-short} `metadata.description` field.
+
+displayName:::
+To change the default value: `cn`, enter the LDAP field to map to the {product-very-short} `metadata.displayName` field.
+
+email:::
+To change the default value: `mail`, enter the LDAP field to map to the {product-very-short} `spec.profile.email` field.
+
+picture:::
+To set a value, enter the LDAP field to map to the {product-very-short} `spec.profile.picture` field.
+
+memberOf:::
+To change the default value: `memberOf`, enter the LDAP field to map to the {product-very-short} `spec.memberOf` field.
+
+set::
+To set a value, enter the hard coded JSON to apply to the entities after ingestion, such as `metadata.customField: 'hello'`.
+
+.. Optional: Enter optional `groups` fields:
+
+map::
+
+rdn:::
+To change the default value: `cn`, enter the relative distinguished name of each entry.
+
+name:::
+To change the default value: `cn`, enter the LDAP field to map to the {product-very-short} `metadata.name` field.
+
+description:::
+To set a value, enter the LDAP field to map to the {product-very-short} `metadata.description` field.
+
+displayName:::
+To change the default value: `cn`, enter the LDAP field to map to the {product-very-short} `metadata.displayName` field.
+
+email:::
+To change the default value: `mail`, enter the LDAP field to map to the {product-very-short} `spec.profile.email` field.
+
+picture:::
+To set a value, enter the LDAP field to map to the {product-very-short} `spec.profile.picture` field.
+
+memberOf:::
+To change the default value: `memberOf`, enter the LDAP field to map to the {product-very-short} `spec.memberOf` field.
+
+members:::
+To change the default value: `member`, enter the LDAP field to map to the {product-very-short} `spec.children` field.
+
+type:::
+To change the default value: `groupType`, enter the LDAP field to map to the {product-very-short} `spec.type` field.
+
+set::
+To set a value, enter the hard coded JSON to apply to the entities after ingestion, such as `metadata.customField: 'hello'`.
+
+.. Optional: Enter optional `tls` fields.
+TLS options only apply when using the secure protocol: `ldaps://`.
++
+.Optional `tls` fields
+[source,yaml]
+----
+ldapOrg:
+  default:
+    tls:
+      rejectUnauthorized: true
+      keys: '/path/to/keys.pem'
+      certs: '/path/to/certs.pem'
+----
+
+rejectUnauthorized::
+Set to `false` to allow self-signed certificates
++
+WARNING: This option is not recommended for production.
+
+keys::
+Enter a file containing private keys in PEM format
+
+certs::
+Enter a file containing cert chains in PEM format
+
+.Verification
+* To verify user and group provisioning, check the console logs.
++
+.Successful synchronization example:
+[source,json]
+----
+
+----