LDAP configuration

Edit online

A server that runs the Lightweight Directory Access Protocol (LDAP) can be configured by more than one component on Kubernetes.

Download the sample configuration XML files from cert-kubernetes and modify a file to match your existing LDAP server. Follow the instructions to apply the modified configuration file in your deployment. Options include IBM Security Directory Server and Active Directory.

External share LDAP configuration

You can find two LDAP configuration sections in the operator custom resource template YAML file, ldap_configuration and ext_ldap_configuration. The LDAP ldap_configuration parameters begin with lc_ and xx.lc_, and are shared by all of the components that use an LDAP. The ext_ldap_configuration parameters are used by IBM Business Automation Navigator and IBM FileNet® Content Manager to list external users (Business Partners) in addition to internal users. Internal users (employees) are listed in the ldap_configuration parameters.

Important: The ext_ldap_configuration parameters apply only if the "External Share" optional IBM FileNet Content Manager component is installed.

Bind secret

For components that require LDAP, use the lc_bind_secret parameter in the template YAML file to locate a secret that includes the ldapUsername and ldapPassword keys. Specify the secret name that you create in the lc_bind_secret parameter.

ldap_configuration:
  lc_bind_secret: ldap-bind-secret

The following command shows how to create the (ext-ldap-bind-secret) secret, for external share, with the needed user names and passwords. 

oc create secret generic ext-ldap-bind-secret \
    --from-literal=ldapUsername="cn=admin,dc=ibm,dc=edu" --from-literal=ldapPassword="<yourLDAPPassword>" \

If you need multiple LDAP configurations, for example ldap_configuration_xxx and ldap_configuration_yyy use a single secret (by default ldap-bind-secret) to include all your LDAP credentials. The operator looks for a username and password for each LDAP ID. 

ldap<lc_ldap_id>Password and ldap<lc_ldap_id>Username
Tip: Specify the hostname of your LDAP server in the lc_ldap_server parameter.

LDAP parameters

Table 1. LDAP configuration
Parameters Description IBM Security Directory Server example values Microsoft Active Directory example values
From 22.0.1-IF005 lc_ldap_precheck The default value is set to true. True enables the validation of the LDAP connection before the installation. If the value is set to false, the operator skips the validation. true true
From 22.0.1-IF005 lc_user_searchbase_list If your LDAP has many sub-trees and the users are not organized in structured groups, then use a list of search bases to add LDAP connections to IAM. ["OU=searchbase1,DC=test,DC=com","OU=searchbase2,DC=test,DC=com","OU=searchbase3,DC=test,DC=com"] ["OU=searchbase1,DC=test,DC=com","OU=searchbase2,DC=test,DC=com","OU=searchbase3,DC=test,DC=com"]
From 22.0.1-IF003 lc_enable_pagination Set to true if you want to enable LDAP pagination in IAM. The default is false. true, false true, false
From 22.0.1-IF003 lc_pagination_size If lc_enable_pagination is set to true, then specify the pagination size. If not specified, the Custom type has a default of 4500. 2000 1000
From 22.0.1-IF003 lc_group_searchbase_list Use this parameter to add custom search bases to IAM. The value must be a list of search bases within square brackets "[]". N/A N/A
lc_selected_ldap_type The type of the directory. IBM Security Directory Server Microsoft Active Directory
lc_ldap_server The hostname must be either the fully qualified domain name or IP address of your LDAP server. HOSTNAME HOSTNAME
lc_ldap_port The LDAP server host port number. 389 636
lc_bind_secret User name and password for the bind user. The LDAP bind secret must have ldapUsername and ldapPassword keys. ldap-bind-secret ldap-bind-secret
lc_ldap_base_dn The LDAP base distinguished name (DN). The base DN subtree is used when you search for user or group entries on the LDAP server. o=mycompany,c=us cn=users,dc=adtest,dc=mycity,dc=mycompany,dc=com
lc_ldap_ssl_enable Specifies whether SSL is used to access LDAP server. true, false true, false
lc_ldap_ssl_secret_name Specifies a secret name that includes an SSL certificate to use when SSL is used to access LDAP server. ldap-ssl-cert ldap-ssl-cert
lc_ldap_user_name_attribute The LDAP attribute that represents the user name. The list can contain multiple values, which are separated by a semicolon. The first relative distinguished name (RDN) must be part of the list. For example, if your user distinguished names (DNs) typically start with uid=..., make sure to include *:uid in the list. *:cn or *:uid user:sAMAccountName
lc_ldap_user_display_name_attr The LDAP attribute to display for the full name of the user. cn or uid sAMAccountName
lc_ldap_group_base_dn The LDAP group base distinguished name (DN). The base DN subtree is used when you search for group entries on the LDAP server. dc=hqpsidcdom,dc=com dc=hqpsidcdom,dc=com
lc_ldap_group_name_attribute The LDAP attribute that represents the group name. *:cn *:cn
lc_ldap_group_display_name_attr The LDAP attribute to display the full name of the group. cn cn
lc_ldap_group_membership_search_filter Search filter for finding group membership. (|(&(objectclass=groupofnames)(member={0}))(&(objectclass=groupofuniquenames)(uniquemember={0}))) (&(cn=%v)(objectcategory=group))
lc_ldap_recursive_search Enable recursive searches. The default value is false. true, false true, false
lc_ldap_group_member_id_map Identifies the group member. Hyphens ("-") are not supported in the value for this parameter due to a defect in the Identity Access and Management (IAM) service REST API. The limitation is removed in an upcoming version. groupOfNames:member;groupOfUniqueNames:uniqueMember memberOf:member
lc_ldap_max_search_results Specify a higher value if you expect more search results. 4500 4500
lc_use_ldap_entity_type Only used by UMS. Enable the enhancement of the LDAP configuration for the UMS SCIM capability. If lc_user_filter or lc_group_filter cannot handle a custom LDAP filter for user or group searches, this section should be enabled. True enables the liberty ldapEntityType configuration and disables the usage of lc_user_filter, lc_group_filter, lc_ldap_group_member_id_map, lc_ldap_user_name_attribute and lc_ldap_group_name_attribute in UMS.

For more information about the ldapEntityType, loginProperty and groupProperties parameters, see the liberty documentation: LDAP User Registry.

true or false true or false
lc_ldap_login_property Only used by UMS when lc_use_ldap_entity_type is set to true. A WIM PersonAccount property that is used to generate the LDAP filter for user searches. uid uid
lc_ldap_entity_type_user.object_class Only used by UMS when lc_use_ldap_entity_type is set to true. The object class that is defined for the given LDAP entity type in the LDAP server. ePerson user
lc_ldap_entity_type_user.search_base Only used by UMS when lc_use_ldap_entity_type is set to true. The LDAP base distinguished name (DN). The base DN subtree is used when you search for user entries on the LDAP server. ou=Users,o=ibm,c=us  
lc_ldap_entity_type_user.searchfilter Only used by UMS when lc_use_ldap_entity_type is set to true. A custom LDAP search expression used while searching for entity types. (|(ObjectCategory=User)(ObjectClass=User)) ObjectCategory=User
lc_ldap_entity_type_group.object_class Only used by UMS when lc_use_ldap_entity_type is set to true. The object class that is defined for the given LDAP entity type in the LDAP server. -groupOfNames -groupOfUniqueNames -groupOfURLs group
lc_ldap_entity_type_group.search_base Only used by UMS when lc_use_ldap_entity_type is set to true. The LDAP base distinguished name (DN). The base DN subtree is used when you search for group entries on the LDAP server. ou=Group,o=ibm,c=us  
lc_ldap_entity_type_group.searchfilter Only used by UMS when lc_use_ldap_entity_type is set to true. A custom LDAP search expression used while searching for entity types. ObjectCategory=Group  
lc_ldap_group_properties.member_attribute.name Only used by UMS when lc_use_ldap_entity_type is set to true. The name of the member.    
lc_ldap_group_properties.member_attribute.object_clas Only used by UMS when lc_use_ldap_entity_type is set to true. The object class of the member attribute.    
lc_ldap_group_properties.member_attribute.scope Only used by UMS when lc_use_ldap_entity_type is set to true. The scope of the member attribute. all,direct,nested all,direct,nested
lc_ldap_group_properties.membership_attribute.nam Only used by UMS when lc_use_ldap_entity_type is set to true. The name of the membership attribute.    
lc_ldap_group_properties.membership_attribute.scope Only used by UMS when lc_use_ldap_entity_type is set to true. The scope of the membership attribute. all,direct,nested all,direct,nested
ad.lc_ad_gc_host The hostname of the Active Directory Global Catalog N/A N/A
ad.lc_ad_gc_port The port of the Active Directory Global Catalog N/A N/A
ad.lc_user_filter Search filter for finding entries in the Active Directory base DN users subtree that match the username. N/A (&(sAMAccountName=%v)(objectcategory=user))
ad.lc_group_filter Search filter for finding entries in the Active Directory base DN group subtree that match the group name. N/A (&(cn=%v)(objectcategory=group))
tds.lc_user_filter Search filter for finding entries in the IBM Directory Server base DN users subtree that match the username. (&(cn=%v)(objectclass=person)) N/A
tds.lc_group_filter Search filter for finding entries in the IBM Directory Server base DN group subtree that match the group name. (&(cn=%v)(|(objectclass=groupofnames)(objectclass=groupofuniquenames)(objectclass=groupofurls))) N/A

Example LDAP_configuration YAML for IBM Security Directory Server

You must adjust the example to match your LDAP configuration.
ldap_configuration:
    # the candidate value is "IBM Security Directory Server" or "Microsoft Active Directory"
    lc_selected_ldap_type: "IBM Security Directory Server"
    lc_ldap_server: "myhost"
    lc_ldap_port: "389"
    lc_ldap_base_dn: "dc=hqpsidcdom,dc=com"
    lc_ldap_ssl_enabled: false
    lc_ldap_ssl_secret_name: ""
    lc_ldap_user_name_attribute: "*:cn"
    lc_ldap_user_display_name_attr: "cn"
    lc_ldap_group_base_dn: "dc=hqpsidcdom,dc=com"
    lc_ldap_group_name_attribute: "*:cn"
    lc_ldap_group_display_name_attr: "cn"
    lc_ldap_group_membership_search_filter: "(|(&(objectclass=groupofnames)(member={0}))(&(objectclass=groupofuniquenames)(uniquemember={0})))"
    lc_ldap_group_member_id_map: "groupofnames:member"
    lc_ldap_max_search_results: 4500
    lc_ldap_recursive_search: false
    tds:
      lc_user_filter: "(&(cn=%v)(objectclass=person))"
      lc_group_filter: "(&(cn=%v)(|(objectclass=groupofnames)(objectclass=groupofuniquenames)(objectclass=groupofurls)))"

Example LDAP_configuration YAML for Microsoft Active Directory

You must adjust the example to match your LDAP configuration.
ldap_configuration:
    # the candidate value is "IBM Security Directory Server" or "Microsoft Active Directory"
    lc_selected_ldap_type: "Microsoft Active Directory"
    lc_ldap_server: "myhost"
    lc_ldap_port: "636"
    lc_ldap_base_dn: "dc=hqpsidcdom,dc=com"
    lc_ldap_ssl_enabled: true
    lc_ldap_ssl_secret_name: "ldap-ssl-cert-secret"
    lc_ldap_user_name_attribute: "user:sAMAccountName"
    lc_ldap_user_display_name_attr: "cn"
    lc_ldap_group_base_dn: "dc=hqpsidcdom,dc=com"
    lc_ldap_group_name_attribute: "*:cn"
    lc_ldap_group_display_name_attr: "cn"
    lc_ldap_group_membership_search_filter: "(&(cn=%v)(objectcategory=group))"
    lc_ldap_group_member_id_map: "memberOf:member"
    lc_ldap_max_search_results: 4500 
    lc_ldap_recursive_search: false
    ad:
      lc_ad_gc_host: ""
      lc_ad_gc_port: ""
      lc_user_filter: "(&(samAccountName=%v)(objectcategory=user))"
      lc_group_filter: "(&(cn=%v)(objectcategory=group))"

Database tuning

If your IBM Security Directory Server LDAP has 200,000+ users, 100+ groups, and multiple group search filters the LDAP might fail to integrate with IAM. You can remove group search filters to see whether it resolves the problem. For more information about tuning, see Advanced tuning mode and How to run REORG, REORGCHK and RUNSTAT on all tables in a database.