diff --git a/assemblies/assembly-authenticating-with-rhbk.adoc b/assemblies/assembly-authenticating-with-rhbk.adoc index 90e01ae8e4..5abe381b41 100644 --- a/assemblies/assembly-authenticating-with-rhbk.adoc +++ b/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] diff --git a/modules/authentication/proc-enabling-user-provisioning-with-ldap.adoc b/modules/authentication/proc-enabling-user-provisioning-with-ldap.adoc new file mode 100644 index 0000000000..388152fcb9 --- /dev/null +++ b/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] +---- + +----