Management of user IDs that are maintained by an LDAP-based user federation

Edit online

Entries can be added to the Keycloak list of user records in three ways.

  • For LDAP-based user federations, entries are added in either of the following ways:
    • They are added when users are synchronized from within the user federation.
    • They are added when a user tries to log in with a verified federation ID, and the corresponding federation has the Import Users field set to ON.
  • For RACF®-based user federations, entries are added when a user tries to log in before the federation ID is verified.

Management of user IDs in Keycloak

To manage users, complete the following steps:
  1. In the IzoaKeycloak security realm, under the Manage section, click Users.

    If no user federations are defined, all manually created user IDs are automatically shown.

  2. If one or more user federations are defined, enter a string in the search field.
    Important: This search looks for user IDs that contain the entered value. A general string can result in a long search time and the retrieval of a large number of matches.

    When you enter a search string, Keycloak searches for the following types of user IDs, and it returns any IDs that match the string:

    • User IDs that are defined by any LDAP user federations
    • User IDs that are manually entered through the Keycloak administrator interface or API
    • User IDs that are bulk loaded for RACF LDAP user federations
    Tip: If a JSON error occurs during the search, ensure that any LDAP custom filters are formatted correctly and that no email addresses are defined in multiple user federation definitions.
  3. To view information for a user record, click the Username link for the record.

    On the Details tab, a Federation link indicates the user federation with which this user is associated.

When user records are added, they are assigned any groups and roles that are mapped by the associated user federation, and they are assigned to any default roles and default groups that are defined in the IzoaKeycloak security realm. By default, every newly created user ID in the IzoaKeycloak realm is assigned to the user role and the basic_user group.

Important:
  • Any user ID that is used to access the Problem Insights GUI or any of its associated services must be assigned a valid role.
  • Group membership can be managed through the Group Membership tab in the user record.
  • Role association can be managed through the Role mapping tab in the user record.

Bulk loading a list of IDs in Keycloak

If many user IDs must be defined to Keycloak, and no method exists for automatically loading them through a user federation definition (which is the situation with the racf provider), the user IDs can be loaded by using the seed-ldap command in the dockerManageZoa.sh script.

The input for this command is a list of user IDs that you want to add to Keycloak and assign a group (assigning the IDs a group is optional). This list must be entered in a file with the following format, and a sample ID list file is included with the zoacommon build:
id access-group-name
Remember: The group names must exactly match the groups that were previously defined in Keycloak.
Run the seed-ldap command from the ZOA_HOME directory:
./bin/dockerManageZoa.sh seed-ldap [force]

When the command runs, it prompts for the full path and name of the user ID list file. Keycloak checks each ID against the defined user federations (in processing order), with the following effect:

  • If a federation returns a positive result, a user record is added to Keycloak, the federation is associated with that user record, and the remaining federations are skipped.
  • Any groups and roles that are mapped by this federation are assigned to the user record.
  • If all federations are processed, and no positive result is returned, an error message is shown, and the user ID is not added to Keycloak.

After the IDs are added to Keycloak, a Keycloak administrator can assign groups and roles to the users by clicking Users under the Manage section.

Because RACF-based user federations that use direct authentication do not access the user data store until a user attempts to log in, the this type of federation is temporarily disabled when loading IDs.

To keep RACF-based federations that are using direct authentication enabled, specify the force parameter. When the force parameter is used with direct authentication, the ID list is processed in the following way:
  • During bulk loading of RACF user IDs, a positive result is returned for all user IDs that are defined in the ID list file.
  • A temporary email address is associated with bulk-loaded RACF user IDs. If an email address field was specified in the RACF user federation, the real address is pulled from RACF the first time that the user ID successfully authenticates.
Important: When you work with the RACF-based user federations that are using direct authentication, carefully review the ID list file before you run the seed-ldap command to prevent the creation of invalid user IDs.