Connecting to your identity provider

You can optionally configure a connection to an existing identity provider, such as an LDAP server. At a minimum, you can use the identity provider to validate users' credentials. However, you can also use your identity provider to manage access to the platform. The information that you specify when you connect to your identity provider determines whether you use the identity provider for password management or for access management.

Restriction: If you configure a connection to an identity provider, all password management tasks, such as changing or resetting passwords, must be completed by the identity provider administrator.

You have two options for connecting to your identity provider:

Mechanism Details
LDAP integration provided by IBM® Software Hub (deprecated) When you install IBM Software Hub, the Identity Management Service is automatically enabled. If you want to use the LDAP integration provided by IBM Software Hub, see Configuring IBM Software Hub to use the embedded LDAP integration.

After you configure IBM Software Hub to use the embedded LDAP integration, see Connecting to your identity provider.

Benefits
You can use LDAP with or without SAML SSO.
You can choose the level of integration with the LDAP server. You can use LDAP to:
  • Validate users' credentials
  • Manage access to the platform
Drawbacks
You can connect to a single LDAP server from each instance of IBM Software Hub.

This method is deprecated and will be removed in a future release.
LDAP integration provided by the IBM Cloud Pak foundational services Identity Management Service When you install IBM Software Hub, the Identity Management Service is automatically enabled.

However, if you upgrade from an older release of IBM Software Hub and the Identity Management Service is not enabled, you can use the setup-iam-integration command to integrate IBM Software Hub with the Identity Management Service provided by IBM Cloud Pak foundational services.

Benefits
The Identity Management Service supports:
  • A wide variety of LDAP servers
  • The ability to connect to multiple LDAP servers
  • More configuration options
Drawbacks
There are no known drawbacks with this mechanism.
Deprecation notice: The LDAP integration provided by IBM Software Hub is deprecated and will be removed in a future release. If you want to use an LDAP server to manage users, you should Integrate with the Identity Management Service
Who needs to complete this task?
The permissions that you must have depend on whether IBM Software Hub is configured to use the Identity Management Service:
Identity Management Service is not configured (default)
To configure the connection to your LDAP server, you must have one of the following permissions:
  • Administer platform
  • Manage platform roles
Identity Management Service is configured
To configure the connection to your identity provider, you must have the Administer platform permission.
When do you need to complete this task?
Complete this task before you give users access to IBM Software Hub.

You can configure a connection to your LDAP server from the Access control page.

Follow the appropriate instructions for your environment:

The Identity Management Service is not enabled

  1. Log in to the IBM Software Hub web client.
  2. From the menu, click Administration > Access control.
  3. Click LDAP configuration.
  4. In the LDAP server information section, provide the following information about your LDAP server:
    Field Description
    LDAP protocol
    • If you are connecting to a secure port on your LDAP server, select ldaps://.
    • If you are connecting to an unsecured port on your LDAP server, select ldap://.
    LDAP hostname Enter the host name of the LDAP server.
    LDAP port Enter the port that you are connecting to.

    Standard ports are 389 for ldap and 636 for ldaps.
    User search base Enter the point in the LDAP tree from which users are searched.

    This is also referred to as the baseDN for the LDAP configuration.
    User search field Enter the LDAP attribute that is used to identify users.

    For example, cn, uid, or sAMAccountName.

    If you plan to use LDAP and a SAML identity provider, ensure that you use the same attribute to identify users. This field should have the same value as the fieldToAuthenticate parameter in your SSO configuration.
    Domain search user If your LDAP server requires authentication to perform lookups, enter the username of a user that can perform lookups on the LDAP server.

    This is also referred to as the bindDN for the LDAP configuration.
    Domain search password If you specified a Domain search user, specify the password for this user.
  5. If you want to add LDAP groups to user groups, select Use LDAP group and provide the following information about your LDAP server:
    Field Description
    Group search base Enter the point in the LDAP tree from which groups are searched.
    Group search field Enter the LDAP attribute that is used to identify groups.

    For example, cn.
  6. If you want to use the LDAP server to manage access to the platform, provide the LDAP attributes that map to the following values:
    Field Description
    First name Enter the LDAP attribute that is used to identify a user's given name. For example, givenName.
    Last name Enter the LDAP attribute that is used to identify a user's surname. For example, sn.
    Email Enter the LDAP attribute that is used to identify a user's email address. For example, mail.
    Group membership If you selected Use LDAP group, enter the LDAP attribute that is used to identify all of the LDAP groups that a user is a member of. For example memberOf.
    Group member field If you selected Use LDAP group, enter the LDAP attribute that is used to identify all of the members of a given group. For example member.

    If you use Microsoft Active Directory and you want to enable the nested groups search, add the following extension ID to the LDAP attribute: :1.2.840.113556.1.4.1941:

    For example: memberOf:1.2.840.113556.1.4.1941:

    Important: If you use nested group search in Microsoft Active Directory, you must disable the default LDAP sync on log in option and enable the periodic sync job. For details, see Syncing IBM Software Hub with your LDAP server.
  7. To verify that you can connect to your LDAP server, enter the following information in the Test connection section:
    Field Description
    Username Enter the username of a user that exists in one of the following locations:
    • The user search base
    • The group search base
    Password Enter the password for the specified user.
    Note: These credentials are not saved.
  8. Click Test connection.
  9. After you verify that you can connect to your LDAP server, click Save.

Syncing IBM Software Hub with your LDAP server

IBM Software Hub provides two options for syncing with your LDAP server:
Sync on log in (default)
This is the default method. When this method is used, the platform syncs each user's data when the user logs in to IBM Software Hub:
  • The first time that a user logs in to IBM Software Hub, the platform creates a user profile and assigns the user the correct user groups based on their LDAP group membership.
  • If the user has logged in before, the platform updates the use group membership based on their LDAP group membership.

This is the recommended method for most environments. If you want to continue using this method, no additional action is required.

Periodic sync job
This option is required if you use nested groups in Microsoft Active Directory. However, this method can cause a lot of overhead for IBM Software Hub instances that have large LDAP groups.

If you want to use this method:

  1. Log in to Red Hat® OpenShift® Container Platform as a project administrator:
    oc login OpenShift_URL:port
  2. Disable the sync on log in (LDAP_SYNC_ON_LOGIN) by running the following command:
    oc patch configmap product-configmap \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--patch '{"data": {"LDAP_SYNC_ON_LOGIN" : "false"}}'
  3. Delete the usermgmt pods:
    oc delete pod \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
-l component=usermgmt
  4. Enable the periodic sync job:
    oc patch cj usermgmt-ldap-sync-cron-job \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--patch '{"spec": {"suspend": false}}'

The Identity Management Service is enabled

You can configure a connection to one or more identity providers from the Identity providers page.

  1. Log in to the IBM Software Hub web client.
  2. From the menu, click Administration > Identity providers.
  3. Click New connection.
  4. Select LDAP. Then, click Next.

    Follow the guidance in Configuring an LDAP connection in the IBM Cloud Pak foundational services documentation.

Syncing IBM Software Hub with your LDAP server when the Identity Management Service is enabled

IBM Software Hub provides two options for syncing with your LDAP server:
Sync on log in (default)
This is the default method. When this method is used, the platform syncs each user's data when the user logs in to IBM Software Hub:
  • The first time that a user logs in to IBM Software Hub, the platform creates a user profile and assigns the user the correct user groups based on their LDAP group membership.
  • If the user has logged in before, the platform updates the use group membership based on their LDAP group membership.

This is the recommended method for most environments. If you want to continue using this method, no additional action is required.

Periodic sync job
You can configure IBM Software Hub to run a periodic LDAP sync job. However, this method can cause a lot of overhead in the following situations:
  • The groups that you created in IBM Software Hub include numerous LDAP groups
  • Some LDAP groups have a large number of users (for example, the groups have more than 1,000 users).
Before you configure the periodic sync job, ensure that:
  • Your LDAP server does not limit the number of entries that are returned by a search.
  • Pagination for SCIM directory searches is enabled. (You can check the LDAP configuration from the IBM Software Hub web client.)

To enable the period sync job:

  1. Log in to Red Hat OpenShift Container Platform as a project administrator:
    oc login OpenShift_URL:port
  2. Determine whether you need to override the default behavior for the LDAP sync job:
    • By default, the LDAP sync job will only sync the group membership of existing IBM Software Hub users. You can override this behavior to automatically onboard any users who part of an LDAP group that is included in an IBM Software Hub group.

      To automatically onboard users from the LDAP groups, set the SYNC_ALL_LDAPUSERS parameter to true in the product-config ConfigMap:

      oc patch configmap product-configmap \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--patch '{"data": {"SYNC_ALL_LDAPUSERS" : "true"}}'
    • By default, the LDAP sync job automatically blocks any users who are no longer in the LDAP server.

      When a user is blocked by the job, the user's profile is updated. The misc attribute in the user's profile includes the following field:{"blocked_from_ldap": true}.

      To prevent users from being automatically blocked, set the BLOCK_STALE_LDAPUSERS parameter to false in the product-config ConfigMap:

      oc patch configmap product-configmap \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--patch '{"data": {"BLOCK_STALE_LDAPUSERS" : "false"}}'
  3. Delete the usermgmt pods:
    oc delete pod \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
-l component=usermgmt
  4. Enable the periodic sync job:
    oc patch cj usermgmt-ldap-sync-cron-job \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--patch '{"spec": {"suspend": false}}'

    The job runs every 2 hours.

  5. Confirm that the usermgmt-ldap-sync-cron-job cron job is running:
    oc get cj usermgmt-ldap-sync-cron-job \
--namespace=${PROJECT_CPD_INST_OPERANDS}

    The command returns output with the following format:

    NAME                          SCHEDULE       TIMEZONE   SUSPEND   ACTIVE   LAST SCHEDULE   AGE
usermgmt-ldap-sync-cron-job   */20 * * * *   <none>     False     0        5h51m           146d

    Ensure that SUSPEND is False.

  6. Wait two hours then confirm that the usermgmt-ldap-sync job was created:
    oc get job --namespace=${PROJECT_CPD_INST_OPERANDS} | grep usermgmt-ldap-sync