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:

• IBM Tivoli Directory Server
• IBM Lotus Domino
• IBM SecureWay Directory Server
• Novell eDirectory
• Sun Java™ System Directory Server
• Netscape Directory Server
• Microsoft Active Directory
• Custom

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.

• Connection name: A unique name for the LDAP connection. Format: 3 - 30 alphanumeric characters; Special characters that are allowed: - _

• Server type: A list of directory server types to which you can connect. Select one from the list.

• Case insensitive user search: Set the value to true or false to enable or disable case sensistivity for the LDAP usernames.

LDAP authentication

Enter authentication information.

• Base DN: The distinguished name of the search base. Example: dc=abc,dc=com. Format: 1 - 255 alphanumeric characters; Special characters that are allowed:

  • =
  • .
  • ,
  • -

• Bind DN: The user who is allowed to search the base DN. Example: cn=admin,dc=abc,dc=com. This parameter is optional. If no user is specified in the Bind DN parameter, the LDAP connection is established without authentication. Format: 0 - 255 alphanumeric characters; white space is allowed; Special characters that are allowed:

  • =
  • .
  • ,
  • -
  • :
  • @
  • (
  • )
  • _
  • \

• Bind DN password: The password of the user who is mentioned in the Bind DN. This parameter is not required if you do not specify a user in the bind DN. A maximum of 255 characters are allowed.

  Note: The configuration of Base DN and Bind DN values must be set as case-sensitive and must be a full distinguished name (DN) path. The DN path, including spaces, commas, and other characters, must be the same as configured in the LDAP server. See the following example:

   Base DN : DC=mycompany,DC=com
   Bind DN : CN=Administrator,CN=Users,DC=mycompany,DC=com
  

  For Base DN, the following values are invalid:

  • dc=mycompany,dc=com because DC is lowercase alphabet.

  • DC=mycompany, DC=com because there is a space between the parameters.

    For Bind DN, the following values are invalid:

  • cn=Administrator,cn=Users,dc=mycompany,dc=com because CN and DC are lowercase alphabets.
  • CN=Administrator,DC=mycompany,DC=com because CN=Users parameter is missing.
  • CN=Administrator,CN=Users, DC=mycompany,DC=com because there is a space between the parameters.

  • CN=administrator,CN=Users,DC=mycompany,DC=com because the administrator parameter value starts with a lowercase alphabet.

    Note: Microsoft Active Directory server does a strict check of Base DN and Bind DN values while it establishes a connection.

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

LDAP server

Enter the server URL for your connection.

• URL: The LDAP directory domain name or IP address, and the LDAP port number. The domain name must begin with ldap(s)://. Example URL: ldap(s)://corpldap.abc.com:389 or ldap://10.10.10.1:389.

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:

• If your LDAP server is compliant with LDAP version 3, then the filters are not sensitive to alphabet case or to white spaces.

• From foundational services version 3.19 and later, Group filter and Group member ID map filters support one or more than one value.

  Enter information about the search filters. For default LDAP filters by LDAP type, see Default LDAP filters by LDAP type.

• Group filter: The filter clause for searching groups. From foundational services version 3.23 and later, IM supports all the special characters but following are the validated and tested special characters: white space, = ; . , & % () {} <> | !

• Group ID map: The filter to map a group name to an LDAP entry. Format: 1 - 255 alphanumeric characters; Special characters that are allowed: white space, * : = ; . , & % () {}

• Group member ID map: The filter to map a user to a group. Format: 1 - 255 alphanumeric characters; Special characters that are allowed: white space, * : = ; . , & % () {}

• User filter: The filter clause for searching users. From foundational services version 3.23 and later, IM supports all the special characters but following are the validated and tested special characters: white space, = ; . , & % () {} <> | !

• User ID map: The filter to map a username to an LDAP entry. Format: 1 - 255 alphanumeric characters; Special characters that are allowed: white space, * : = ; . , & % () {}

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:

• groupFilter = (&(cn=%v)((objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))
• groupMemberIdMap = groupOfNames:member;groupOfUniqueNames:uniqueMember

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