Importing LDAP users

Importing users

Import users from an LDAP registry by configuring user federation within Keycloak.

1. Log in to the Platform UI as a user with realm management permissions. For more information, see Cloud Pak roles and permissions.

2. Click the Navigation Menu icon next to IBM Cloud Pak for Integration in the banner, then click Administration > Access control. The Keycloak access control console opens.

3. In the navigation pane, click User federation. The User federation page opens.

4. Create or update an LDAP provider.

   • To create a new LDAP provider, click Add new provider and select LDAP.

   • If you want to configure an existing provider, click the name of the LDAP provider you want to edit. A configuration page opens.

     Tip: If there are no existing LDAP providers, click Add Ldap providers on the User federation page to open the configuration.

5. Update the fields in the General options section.

   • If this is a new provider, enter a name in the UI display name field.

   • For Vendor, click to open the list and select a vendor. Keycloak populates default values for the vendor you select.

6. Enter other LDAP registry settings as needed.

   Connection and authentication settings

   Because Cloud Pak for Integration manages Keycloak for you, follow the procedure in the "Adding certificates to the Keycloak trust store" section of Keycloak configuration instead of configuring the fields in this section.

   LDAP searching and updating

   Edit mode - Set to READ_ONLY.

   In this mode, Keycloak does not need to fully manage the LDAP server. The user cannot change the username, email, first name, last name, and other mapped attributes. Red Hat build of Keycloak returns an error any time a user attempts to update these fields. Password updates are not supported.

   Synchronization settings

   The values in this section synchronize LDAP users to the Red Hat build of Keycloak.

   Import users - When set to On, the LDAP provider handles importing LDAP users into the Red Hat build of Keycloak local database. The first time a user logs in or is returned as part of a user query (for example, using the search field in the admin console), the LDAP provider imports the LDAP user into the Red Hat Build of Keycloak database. During authentication, the LDAP password is validated.

   Sync Registrations - Set to On if you want new users created by Red Hat build of Keycloak added to LDAP.

   To sync your LDAP users into the Red Hat Build of Keycloak database, configure one of the two available synchronization options:

   • Periodic full sync - This type synchronizes all LDAP users into the Red Hat Build of Keycloak database. The LDAP users already in Red Hat build of Keycloak, but different in LDAP, directly update in the Red Hat Build of Keycloak database.

   • Periodic changed users sync - When synchronizing, Red Hat Build of Keycloak creates or updates users that are created or updated after the last sync only. If you create a new LDAP provider, you might want to begin by enabling Periodic full sync, then later change to Periodic Changed users sync.

   Kerberos integration

   Allow Kerberos authentication - Enable Kerberos/SPNEGO authentication in the realm with user data provisioned from LDAP.

7. Click Save.

For more information, see 4.3. Lightweight Directory Access Protocol (LDAP) and Active Directory in the Red Hat documentation.

Importing groups

The following procedure imports groups from your LDAP directory. However, you can also assign LDAP users to Keycloak groups. For more information on Keycloak groups, see Managing users in Keycloak.

Import groups from an LDAP registry by adding a mapper to your LDAP provider.

1. Log in to the Platform UI as a user with realm management permissions. For more information, see Cloud Pak roles and permissions.

2. Click the Navigation Menu icon next to IBM Cloud Pak for Integration in the banner, then click Administration > Access control. The Keycloak access control console opens.

3. In the navigation pane, click User federation.

4. Select the LDAP provider from which you want to import groups.

5. Click the Mappers tab.

6. Click Add mapper.

   1. Enter a name (for example, groups).

   2. Select the group-ldap-mapper type.

   3. Enter your LDAP registry settings.

7. Click Save.

   The groups become available in Keycloak when users are synchronized from the LDAP registry. You can trigger synchronization manually by opening your LDAP provider configuration and using the Action menu.j

   LDAP mappers

   : LDAP mappers are listeners triggered by the LDAP Provider. They provide another extension point to LDAP integration. LDAP mappers are triggered when:

   • Users log in by using LDAP.

   • Users initially register.

   • The Admin Console queries a user.

   When you create an LDAP Federation provider, Red Hat build of Keycloak automatically provides a set of mappers for this provider. User can develop their own mappers and update or delete existing mappers.

   • User Attribute Mapper - Specifies which LDAP attribute maps to the attribute of the Red Hat Build of Keycloak user. For example, you can configure the mail LDAP attribute to the email attribute in the Red Hat Build of Keycloak database. This mapper implementation always has a one-to-one mapping. User Attribute mappers map basic Red Hat build of Keycloak user attributes, such as username, firstname, lastname, and email, to corresponding LDAP attributes. You can extend these by providing your own attribute mappings.

   • FullName Mapper - Specifies the full name of the user. Red Hat Build of Keycloak saves the name in an LDAP attribute (usually cn) and maps the name to the firstName and lastname attributes in the Red Hat Build of Keycloak database. Having cn contain the full name of the user is common for LDAP deployments.

   • Hardcoded Attribute Mapper - Adds a hardcoded attribute value to each Red Hat Build of Keycloak user that is linked with LDAP. This mapper can also force values for the enabled or emailVerified user properties.

   • Role Mapper - Configures role mappings from LDAP into Red Hat Build of Keycloak role mappings. A single role mapper can map LDAP roles (usually groups from a particular branch of the LDAP tree) into roles that correspond to a specified client’s realm roles or client roles. You can configure more Role mappers for the same LDAP provider. For example, you can specify that role mappings from groups under ou=main,dc=example,dc=org map to realm role mappings, and that role mappings from groups under ou=finance,dc=example,dc=org map to client role mappings of client finance.

   • Hardcoded Role Mapper - Grants a specified Red Hat build of Keycloak role to each Red Hat build of Keycloak user from the LDAP provider.

   • Group Mapper - This mapper maps LDAP groups from a branch of an LDAP tree into groups within Red Hat build of Keycloak. This mapper also propagates user-group mappings from LDAP into user-group mappings in Red Hat Build of Keycloak.

   • MSAD User Account Mapper - This mapper is specific to Microsoft Active Directory (MSAD). It can integrate the MSAD user account state into the Red Hat Build of Keycloak account state, such as enabled account or expired password. This mapper uses the userAccountControl, and pwdLastSet LDAP attributes, which are specific to MSAD and not the LDAP standard. For example, if the value of pwdLastSet is 0, the Red Hat Build of Keycloak user must update their password. The result is an UPDATE_PASSWORD required action added to the user. If the value of userAccountControl is 514 (disabled account), the Red Hat Build of Keycloak user is disabled.

   • Certificate Mapper - This mapper maps X.509 certificates. Red Hat Build of Keycloak uses it in conjunction with X.509 authentication and a full certificate in PEM format as an identity source. This mapper behaves similarly to the User Attribute Mapper, but Red Hat Build of Keycloak can filter for an LDAP attribute storing a PEM or DER format certificate. Enable Always Read Value From LDAP when using this mapper.

What to do next

Assign permissions to LDAP users. For more information, see Cloud Pak roles and permissions.