LDAP configuration

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 the folders on GitHub 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.

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 for environments that use the 2 LDAP method for external share. If you configure external share by integrating with UMS or another identity provider to manage external users, leave the ext_ldap_configuration settings commented out.

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

New in 20.0.2 The following commands shows how to create the (ldap-bind-secret) secret with the needed usernames and passwords.

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

New in 20.0.2 The following commands shows how to create the (ext-ldap-bind-secret) secret, for external share, with the needed usernames and passwords.

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

For 20.0.1 The following command shows how to create the (ldap-bind-secret) secret with the needed usernames and passwords. (This example includes credentials for the optional external LDAP method for external share, which might not apply in your environment.)

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

Where ldapUsername is the bindDN property of your LDAP server with base64 encoded, and ldapPassword is the bindPassword property of your LDAP server with base64 encoded.

Important:

For 20.0.1 If you enable ODM and the shared LDAP in the custom resource you must add the following parameters to the web security secret.

--from-literal=lc_ldap_bind_dn="cn=admin,dc=ibm,dc=edu" 
--from-literal=lc_ldap_bind_password="<yourLDAPPassword>"

For more information, see Configuring user access.

If you need an LDAP SSL configuration, you must also have the sslEnabled="true" and sslRef="odmDefaultSSLConfig" properties in the ldapRegistry tag of the webSecurity.xml file.

<ldapRegistry id="ldap" realm="OpenLdapRealm" host="openldap" port="636" ldapType="Custom" 
sslEnabled="true" sslRef="odmDefaultSSLConfig" ignoreCase="true" recursiveSearch="true"
baseDN="dc=example,dc=org" bindDN="cn=admin,dc=example,dc=org" bindPassword="admin">
   ...
</ldapRegistry>

If you need to add these properties to an installed ODM instance, update the secret with the modified webSecurity.xml file, and then restart the ODM pods by running the following commands:

oc get pods | grep <CR_NAME>-odm
oc delete <odm-pod-name>

Tip: Specify the hostname of your LDAP server in the lc_ldap_server parameter. If routes are created automatically, make sure that you set the hostname in the ums_configuration section of your YAML file.

ums_configuration:
   service_type: Ingress
   hostname: <your external UMS host name>.nip.io

Table 1. LDAP configuration
Parameters	Description	IBM Security Directory Server example values	Microsoft Active Directory example values
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	389
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 full name of the user.	: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.	(&(cn=%v)(\|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))	(&(cn=%v)(objectcategory=group))
lc_ldap_group_member_id_map	Identifies the group member.	groupofnames:member	memberOf:member
lc_ldap_max_search_results	Specify a higher value if you expect more search results.	4500	4500
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

The following YAML shows an example ldap_configuration section:

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
    ad:
      lc_ad_gc_host: ""
      lc_ad_gc_port: ""
      lc_user_filter: "(&(cn=%v)(objectclass=person))"
      lc_group_filter: "(&(cn=%v)(|(objectclass=groupofnames)(objectclass=groupofuniquenames)(objectclass=groupofurls)))"
    tds:
      lc_user_filter: "(&(cn=%v)(objectclass=person))"
      lc_group_filter: "(&(cn=%v)(|(objectclass=groupofnames)(objectclass=groupofuniquenames)(objectclass=groupofurls)))"