Configuring LDAP connection

Configure an LDAP (Lightweight Directory Access Protocol) connection for your product cluster.

You must connect an LDAP directory with your product cluster. You can then add users from your LDAP directory into your cluster.

IM supports the LDAPEntityType configuration for LDAP User and Group entities as default to define the ObjectClass or ObjectCategory attributes automatically in the Liberty XML file. The ObjectClass or ObjectCategory attributes of the User and Group are retrieved from the User and Filter fields that are defined in the LDAP IDP V3 idsource API. For existing LDAP connection, you need to restart the platform-auth-service pods to enable the LDAPEntityType configuration. For more information, see Enabling LDAPEntityType configuration for existing LDAP User and Group entities.

The following LDAP types are supported:

Note: You can configure an account lockout policy when you set up your LDAP server. An account lockout policy provides more security by restricting access to the account if multiple login attempts fail.

Important: If Platform UI (ibm-platformui-operator) service is installed, user management capabilities are available for managing LDAP user and user groups roles, and permissions. You can add an LDAP or OpenShift user to your cluster. When you add a user, you must specify the OpenShift or LDAP login ID of the user in the Username field.

Required user type or access level: Cluster administrator or Cloud Pak administrator

Enabling LDAPEntityType configuration for existing LDAP User and Group entities

Restart the platform-auth-service pods to enable the LDAPEntityType configuration for the existing LDAP connection.

  1. Get the platform-auth-service pod name.

    oc get pods -n <your-foundational-services-namespace> | grep platform-auth-service
    
  2. Delete the platform-auth-service pod.

    oc delete pod <platform-auth-service-pod-name> -n <your-foundational-services-namespace>
    

The procedure is not applicable for new LDAP connection.

Connecting to your LDAP directory

Follow these steps to set up your LDAP connection.

Pre-requisite: Install the cluster. Once the cluster is installed, the admin username, password, and the URL are displayed.

  1. Log on to the console by using the URL and enter the username and password.

    Note: The console can be Platform UI or Common UI. For more information, see Accessing your cluster by using the console.

  2. From the navigation menu, click Identity and access > Identity providers.

  3. Click Create Connection. The "LDAP connection" page is displayed.
  4. Enter the following details to set up your LDAP connection.

    Note: You can configure multiple LDAP connection instances to the same LDAP server. However, ensure that you meet the following requirements:

    • Both the Base DN and connection Name must be unique.
    • The username from the LDAP attribute that you specified in the User ID map must be unique across your LDAP instances. This requirement is because WebSphere Liberty uses federated registries for the multiple LDAPs by default. For more information, see Configuring LDAP user registries in Liberty.
    • IBM Cloud Pak foundational services provides a default admin user ID. If your LDAP registries have admin user IDs, you must rename the default admin user ID that foundational services provides. For more information about how to change the default name, see Changing the default admin username or Changing the cluster administrator username.

LDAP connection

Enter connection information.

LDAP authentication

Enter authentication information.

You can click Test connection to verify whether the LDAP connection details are valid.

LDAP server

Enter the server URL for your connection.

For LDAP over SSL (LDAPS), you must use the domain name, and the URL must begin with ldaps://. Example URL: ldaps://corpldap.abc.com:636.

Note: If you are unable to connect to your LDAPS server by using the host name, add the IP address and host name of the LDAPS server in your local DNS. The LDAPS server host name must be resolvable from your master node.

LDAP filters

Note:

  1. Click Create.

Your cluster is now connected with your LDAP directory.

Note: To block other hosts, see Adding egress firewall to prevent DNS loop to unknown hosts

Note: If you are using an LDAPS connection, the SSL (Secure Sockets Layer) certificates that are required for your LDAPS connection are automatically configured when you connect with your directory.

If your LDAPS connection is not successful, you can try setting up the connection manually. For more information, see Configuring LDAP over SSL.

Next, you can add your LDAP users and user groups to your cluster.

Note: The Cluster Administrator or Cloud Pak administrator must provide the Administrator with view access to the LDAP directory. Only then, the Administrator can use the console to add users or groups to teams.

Default LDAP filters by LDAP type

Note: There is a limitation on liberty, that is, the LDAP userFilter and groupFilter fields must contain an attribute with =%v value. For example, (cn=%v) for Cloud Pak and Cloud Pak for data login flow to work.

The following table represents the name of the filters, their data types and their default values. The groupFilter and groupMemberIdMap can have one or more than one default value from foundational services version 3.19 and later.

For example:

Table 1. List of default IBM Tivoli Directory Server LDAP filters
Attribute name Data type Default value
groupFilter String (&(cn=%v)(objectclass=groupOfUniqueNames))
groupIdMap String *:cn
groupMemberIdMap String groupOfUniqueNames:uniquemember
userFilter String (&(emailAddress=%v)(objectclass=person))
userIdMap String *:emailAddress
Table 2. List of default Custom Server LDAP filters
Attribute name Data type Default value
groupFilter String (&(cn=%v)(objectclass=groupOfUniqueNames))
groupIdMap String *:cn
groupMemberIdMap String groupOfUniqueNames:uniquemember
userFilter String (&(uid=%v)(objectclass=ePerson))
userIdMap String *:uid
Table 3. List of default Microsoft Active Directory LDAP filters
Attribute name Data type Default value
groupFilter String (&(cn=%v)(objectcategory=group))
groupIdMap String *:cn
groupMemberIdMap String memberOf:member
userFilter String (&(sAMAccountName=%v)(objectclass=person))
userIdMap String user:sAMAccountName
Table 4. List of default IBM Lotus Domino LDAP filters
Attribute name Data type Default value
groupFilter String (&(cn=%v)(objectclass=dominoGroup))
groupIdMap String *:cn
groupMemberIdMap String dominoGroup:member
userFilter String (&(uid=%v)(objectclass=Person))
userIdMap String person:uid
Table 5. List of default IBM SecureWay Directory Server LDAP filters
Attribute name Data type Default value
groupFilter String (&(cn=%v)((objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))
groupIdMap String *:cn
groupMemberIdMap String groupOfNames:member;groupOfUniqueNames:uniqueMember
userFilter String (&(uid=%v)(objectclass=ePerson))
userIdMap String *:uid
Table 6. List of default Sun Java System Directory Server LDAP filters
Attribute name Data type Default value
groupFilter String (&(cn=%v)(objectclass=ldapsubentry))
groupIdMap String *:cn
groupMemberIdMap String nsRole:nsRole
userFilter String (&(uid=%v)(objectclass=inetOrgPerson))
userIdMap String inetOrgPerson:uid
Table 7. List of default Netscape Directory Server LDAP filters
Attribute name Data type Default value
groupFilter String (&(cn=%v)((objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))
groupIdMap String *:cn
groupMemberIdMap String groupOfNames:member;groupOfUniqueNames:uniqueMember
userFilter String (&(uid=%v)(objectclass=inetOrgPerson))
userIdMap String inetOrgPerson:uid
Table 8. List of default Novell eDirectory LDAP filters
Attribute name Data type Default value
groupFilter String (&(cn=%v)(objectclass=groupOfNames))
groupIdMap String *:cn
groupMemberIdMap String groupOfNames:member
userFilter String (&(cn=%v)(objectclass=Person))
userIdMap String person:cn

Adding egress firewall to prevent DNS loop to unknown hosts

Run the following command to retrieve the egress network policy:

oc get egressnetworkpolicy ldap-firewall

Sample output:

NAME            AGE
ldap-firewall   16m

The following sample YAML spec defines the LDAP firewall egress network policy. To block other hosts, update the spec to specify the hosts that you want to deny access. Then, save and apply the updated policy.

apiVersion: network.openshift.io/v1
kind: EgressNetworkPolicy
metadata:
  name: ldap-firewall
spec:
  egress:
  - type: Allow
    to:
      dnsName: bluepages.ibm.com
  - type: Allow
    to:
      cidrSelector:  9.30.192.0/24
  - type: Deny
    to:
      cidrSelector: 0.0.0.0/0
  podSelector:
    matchLabels:
      app: platform-auth-service
  policyType:
  - Egress