Configuring LDAP

After you have installed IBM® Cloud Infrastructure Center, you can optionally configure it to work with an existing Lightweight Directory Access Protocol (LDAP) server.

Prerequisites

Ensure that a supported LDAP server is installed and running in your environment. See Hardware and software requirements for the list of supported LDAP servers.

By default, IBM Cloud Infrastructure Center uses the local operating system to manage users and groups. See Configure operating system users and groups for details.

Notes

  • You might need to configure the firewall to allow LDAP or LDAPS traffic.

  • Switching to LDAP restarts the HTTP service under which the identity service (Keystone) is running.

  • If SELinux is enabled and in enforcing mode, ensure that it does not prevent the httpd service from accessing the CA certificate file or directory that you specify.

  • LDAP servers typically limit the number of users and groups that can be returned for an LDAP query. This limit is configured on the LDAP server. Contact your LDAP administrator to obtain the current limit in your environment. For IBM Tivoli Directory Server for z/OS with SDBM backend configured (using SDBM, the RACF database backend of the LDAP server, the LDAP server can provide remote LDAP access to the user, group, connection, and general resource profile information stored in RACF), IBM Cloud Infrastructure Center uses the traditional search (extended search set to off) and it is subject to the 4096-lines output restriction imposed by the RACF R_admin "run command" interface. It is highly recommended that appropriate user and group filters be part of your IBM Cloud Infrastructure Center LDAP configuration in order to limit the number of entities returned by LDAP searches and therefore avoid size limit error:

    Unable to retrieve data from the server. url: https://management_ip/icic/openstack/identity/v3/users.
    Explanation:
    Number of User/Group entities returned by LDAP exceeded size limit. Contact your LDAP administrator.
    Response:
    Review the explanation and try the request again.

  • For security considerations, it is recommended that you limit the maximum number of password login failures in the backend LDAP server, for example, configure the parameters pwdMaxFailure and pwdLockout for openldap.

  • If your LDAP server is using Posix NIS schema and does not provide an 'enabled' attribute for users, IBM Cloud Infrastructure Center can't emulate an 'enabled' attribute for users. In this case, when you configure LDAP, you must enter 'n' to the question Emulate an 'enabled' attribute for users? [y]:, otherwise the LDAP user can't log in to IBM Cloud Infrastructure Center after configuration is complete. If you need the 'enabled' attribute for users, contact your LDAP administrator and configure it on the LDAP server.

  • Before you configure LDAP, make sure the user and group are configured correctly on the LDAP server. For example, make sure the group can list the members, you can find the user's group from the member attribute. The following example, shows how to check the configuration on LDAP server with NIS schema:

    [root@9 ~]# ldapsearch -h example.ibm.com -p 6389 -D "cn=root" -w password -b "cn=group1,o=ibm,c=us"  -s sub
    # extended LDIF
    #
    # LDAPv3
    # base <cn=group1,o=ibm,c=us> with scope subtree
    # filter: (objectclass=*)
    # requesting: ALL
    #

    # group1, ibm, us
    dn: cn=group1,o=ibm,c=us
    objectclass:: cG9zaXhHcm91cCA=
    objectclass: top
    cn: group1
    gidnumber: 1
    memberuid: cn=icicu1,ou=users, o=ibm, c=us
    memberuid: cn=icicu2,ou=users, o=ibm, c=us

    # search result
    search: 2
    result: 0 Success

    # numResponses: 2
    # numEntries: 1

    [root@9 ~]# ldapsearch -h example.ibm.com -p 6389 -D cn=root -w password -b "o=ibm,c=us" "(memberuid=cn=icicu3,ou=users,o=ibm,c=us)"
    # extended LDIF
    #
    # LDAPv3
    # base <o=ibm,c=us> with scope subtree
    # filter: (memberuid=cn=icicu3,ou=users,o=ibm,c=us)
    # requesting: ALL
    #

    # group2, ibm, us
    dn: cn=group2,o=ibm,c=us
    objectclass: posixGroup
    objectclass: top
    cn: group2
    gidnumber: 2
    memberuid: cn=icicu3,ou=users,o=ibm,c=us
    memberuid: cn=icicu4,ou=users,o=ibm,c=us

    # search result
    search: 2
    result: 0 Success

    # numResponses: 2
    # numEntries: 1

Configuring command

Use the icic-config identity repository command to configure LDAP. For instructions about how to use this command, run icic-config identity repository --help. When you run this command, you must provide information about your LDAP configuration. Be sure to specify a user with -- user parameter or a group with --group parameter for the initial administrator role assignment so that at least one user has administrator permissions. The user or group will be assigned the administrator role of project 'ibm-default' and used as the cloud administrator who can then create additional projects and role assgignments as required.

If you want to make changes after you have successfully configured LDAP as the identity backend of IBM Cloud Infrastructure Center, for example, add a user filter or a group filter, use the icic-config identity repository command parameters and run with '--quiet' mode.

Configuring samples

Upcoming are some examples of different LDAP server configurations including some examples running in quiet mode.

Example 1: Configure an OpenLDAP or a 389 Directory Server without a user filter and a group filter

[root@uitstcnt certs]# icic-config identity repository --type ldap --anon --user san.zhang
LDAP user/group information will be stored in IBM Cloud Infrastructure Center database.
Do you want to proceed? [y/n] y


Configuring for IBM Cloud Infrastructure Center LDAP.

RACF as z/OS LDAP backend? [n]:
URL [ldap://localhost]: ldap://example.ibm.com:389
CA certificate file [None]: /etc/openldap/certs/ca.crt
User tree DN [ou=Users,dc=example,dc=com]: ou=Users,dc=demo,dc=com
User filter [None]:
User object class [inetOrgPerson]:
User ID attribute [uid]: cn
User name attribute [cn]:
User mail attribute [email]: mail
User description attribute [description]:
Group tree DN [ou=Groups,dc=example,dc=com]: ou=Groups,dc=demo,dc=com
Group filter [None]:
Group object class [groupOfNames]:
Group ID attribute [cn]:
Group name attribute [cn]:
Group member attribute [member]:
Group description attribute [description]:
Query scope [one]:
The LDAP server provides an 'enabled' attribute for users? [n]:
Emulate an 'enabled' attribute for users? [y]:
Group DN to emulate an 'enabled' attribute for users [cn=enable_group,ou=Groups,dc=demo,dc=com]:


Updating /etc/keystone/domains/keystone.Default.conf


Removing assignments...
Adding default assignment for user "san.zhang"


Stopping httpd services...
Starting httpd services...
An admin role assignment has been created for san.zhang. Use this assignment to create other role assignments by logging in to IBM Cloud Infrastructure Center user interface.

Example 2: Add an OpenLDAP or a 389 Directory Server user filter in quiet mode

[root@uitstcnt ~]# icic-config identity repository --type ldap --user-filter "(cn=*g)" --quiet
LDAP user/group information will be stored in Cloud Infrastructure Center database.
Do you want to proceed? [y/n] y


Configuring IBM Cloud Infrastructure Center for LDAP.


fetching assignments...


Updating /etc/keystone/domains/keystone.Default.conf




Stopping httpd services...
Starting httpd services...
No new role assignments were created. Pre-existing role assignments were preserved.

Example 3: Configure a z/OS LDAP with SDBM backend configured without a user filter and a group filter

[root@uitstcnt ~]# icic-config identity repository --type ldap --user icicu1
LDAP user/group information will be stored in IBM Cloud Infrastructure Center database.
Do you want to proceed? [y/n]y


Configuring IBM Cloud Infrastructure Center for LDAP.


RACF as z/OS LDAP backend? [n]: y
URL [ldap://localhost]: ldaps://example.ibm.com:6636
CA certificate file [/etc/openldap/certs/icictest.new.pem]:
Bind user name [racfid=userid,profiletype=user,suffix]: racfid=ICICADM,profiletype=user,sysplex=plex2
Password:
User tree DN [profiletype=user,suffix]: profiletype=user,sysplex=plex2
User filter [None]:
User object class [racfuser]:
User ID attribute [racfid]:
User name attribute [racfid]:
User mail attribute [racfemail]:
User description attribute [None]:
Group tree DN [profiletype=group,suffix]: profiletype=group,sysplex=plex2
Group filter [None]:
Group object class [racfgroup]:
Group ID attribute [racfid]:
Group name attribute [racfid]:
Group member attribute [racfgroupuserids]:
Group description attribute [None]:
Query scope [one]:
The LDAP server provides an 'enabled' attribute for users? [n]:
Emulate an 'enabled' attribute for users? [y]:
Group DN to emulate an 'enabled' attribute for users [racfid=enable_group,profiletype=group,suffix]: racfid=enable_group,profiletype=group,sysplex=plex2


 Updating /etc/keystone/domains/keystone.Default.conf


 Removing assignments...
 Adding default assignment for user "ICICU1"


 Stopping httpd services...
 Starting httpd services...
 An admin role assignment has been created for ICICU1. Use this assignment to create other role  assignments by logging in to IBM Cloud Infrastructure Center user interface.

Example 4: Add a z/OS LDAP group filter with SDBM backend configured in quiet mode

[root@uitstcnt ~]# icic-config identity repository --type ldap --group-filter "(racfid=cictest)" --quiet
LDAP user/group information will be stored in IBM Cloud Infrastructure Center database.
Do you want to proceed? [y/n] y


Configuring IBM Cloud Infrastructure Center for LDAP.


fetching assignments...


Updating /etc/keystone/domains/keystone.Default.conf




Stopping httpd services...
Starting httpd services...
No new role assignments were created. Pre-existing role assignments were preserved.

Notes

  • If you switch to LDAP from the local operating system for your identity repository, all existing role assignments are removed because they apply to users and groups that are no longer available. For example, if you switch from the local operating system to LDAP, the users and groups that were defined in the local operating system do not exist in LDAP. This means that the role assignments do not exist in LDAP. To avoid using losing user information, make sure you consider how to manage users and groups in the planning phase before your switch to LDAP.

  • If you switch to LDAP from the local operating system for your identity repository, all existing resources including projects, hosts, network, storages and virtual machines are preserved. All existing projects are assigned to the LDAP user which you configured.

LDAP server information to obtain from LDAP administrator

See Table 1 for the types of information you need to obtain from your LDAP administrator. By default, the LDAP server is configured in secure mode.

Table 1. Configure IBM Cloud Infrastructure Center to use an LDAP server

Attribute name Description Example
URL The URL of the LDAP server. ldap://129.32.200.252
Use TLS Specifies whether to use StartTLS to secure the connection. This is not relevant for ldaps:// URLs. Warning: Choosing not to use TLS with an ldap:// URL is not secure and is highly discouraged. y
CA certificate file Specifies the path and name of a PEM-formatted file in the local file system that contains the certificates of Certificate Authorities that should be trusted. Either this or "CA certificate directory" (see next attribute) is required for ldaps:// URLs or when using StartTLS on ldap:// URLs. /etc/pki/tls/certs/ca-bundle.crt
CA certificate directory Specifies the local file system path of a directory that contains (in separate files) the certificates of Certificate Authorities which should be trusted. In addition, this directory must be managed using the OpenSSL c_rehash utility. Either this or "CA certificate file" (see previous attribute) is required for ldaps:// URLs or when using StartTLS on ldaps:// URLs. /etc/pki/my-ca-dir
Anonymous bind If Anonymous bind is set to 'y', then a username and password are not required. Anyone can connect to the LDAP server and search, although the searchable data can be limited by the LDAP administrator. Specify y or n. For IBM Tivoli Directory Server for z/OS with SDBM backend configured, this is not needed as it does not allow anonymous bind. n
User name Maps to the user profile on the LDAP server. This user is used to authenticate to the LDAP server while configuring the LDAP server in a non-anonymous mode. Note: The bind user should be the 'racfowner' of all users and groups which will be visible to IBM Cloud Infrastructure Center. cn=Administrator,dc=ibm,dc=com or racfid=admin,profiletype=user,cn=sdbm
Password The LDAP attribute that maps to the user's password. password
User tree DN The user tree name that uniquely identifies the user entry in the directory. ou=people,dc=ibm,dc=com or profiletype=user,cn=sdbm
User filter Limits which users are visible to IBM Cloud Infrastructure Center. LDAP servers typically limit the number of users and groups that can be returned for an LDAP query. This uses the standard LDAP filter syntax. Note: For IBM Tivoli Directory Server for z/OS with SDBM backend configured, user filter only support racfid=xyz or racfgroupid=xyz. (\|(uid=bob)(uid=joan)(uid=sam)) or (racfid=xyz) or (racfgroupid=xyz)
User object class The object class that is supported by the LDAP server. Provide the object class property name used to configure the user in the LDAP server as input. This might change based on the LDAP configuration. inetOrgPerson or racfuser
User ID attribute The LDAP attribute that maps to the user ID. This attribute is often named uid. The characters can be a-z, A-Z, DBCS characters, period (.), dash (-), and underscore ( _ ). uid or racfid
User name attribute The LDAP attribute to be used by IBM Cloud Infrastructure Center to search the user name. Note: If the ldap use uid as the attribute to identify the users, this parameters must setup as uid uid or racfid
User mail attribute The LDAP attribute to be used by IBM Cloud Infrastructure Center to search for the user’s primary email address. Note: This is not the user’s email address but the attribute as configured at the LDAP server. For IBM Tivoli Directory Server for z/OS with SDBM backend configured, racfemail attribute needs WORKATTR segment which is a non-base segment. To list information from segments other than the BASE segment for a user profile, including your own, one of the following conditions must be true: You have the SPECIAL, AUDITOR or ROAUDIT attribute or You have at least READ authority to the desired field within the segment through field-level access checking. Refer to the link for detail RACF command. email or racfemail
User description attribute The LDAP attribute that contains a text description of the user. description
Group tree DN The group tree name that uniquely identifies an entry in the directory. ou=group,dc=ibm,dc=com or profiletype=group,cn=sdbm
Group filter Limits which groups are visible to IBM Cloud Infrastructure Center. LDAP servers typically limit the number of users and groups that can be returned for an LDAP query. This uses the standard LDAP filter syntax. Note: For IBM Tivoli Directory Server for z/OS with SDBM backend configured, user filters only support racfid=xyz. (\|(cn=admin)(cn=deployer)(cn=viewer)) or (racfid=xyz)
Group object class The object class of the group that uses the member attribute. This is the object class property name used to configure the groups in the LDAP server. This could change based on the LDAP configuration. groupOfNames or racfgroup
Group ID attribute The LDAP attribute that maps to the name that is used to identify a group in the LDAP server. The characters can be a-z, A-Z, DBCS characters, period (.), dash (-), and underscore ( _ ). gidNumber or racfid
Group name attribute The LDAP attribute that specifies the group name for a group entry. This attribute is often named cn. cn or racfid
Group member attribute The LDAP attribute that specifies the names of group members for a group entry. This attribute is often named member. member or racfgroupuserids
Group description attribute The LDAP attribute that contains a text description of the group. description
Query scope Indicates how deeply to search under the user and group tree DNs. Supported values: oneSearch only entries that are immediate subordinates of the base DN. This is the default.subSearch the entire subtree of the base DN. one
Chase referrals Indicates whether to follow LDAP referrals. Chasing referrals only works if anonymous binding is allowed by the domain controller to which the referral points. The default setting is False. Setting this value to True could decline due to processing overhead. If you experience delay logging into IBM Cloud Infrastructure Center, set this value to False. For more information, see LDAP referrals. True
The LDAP server provides an 'enabled' attribute for users? Indicates whether the configure LDAP server provides an 'enabled' attribute for users. This property maybe helpful for terraform usage. Y
Emulate an 'enabled' attribute for users? Indicates whether emulate an 'enabled' attribute for the LDAP users with IBM Cloud Infrastructure Center. Y
Group DN to emulate an 'enabled' attribute for users Users in this group are emulated an 'enabled' attribute. This group DN must be under the group tree DN. cn=enable_group,ou=Groups,dc=demo,dc=com or racfid=enable_group,profiletype=group,sysplex=plex2

The SSL/TLS file certificate must be copied from your LDAP server directory. Refer to your LDAP server documentation for more information about the SSL/TLS usage.