Preparing an LDAP configuration file

The following describes how to prepare an LDAP client configuration file using posixGroup LDAP groups and posixAccount user accounts. If using LDAP user management, the configuration file is needed when provisioning a zCX instance.

An LDAP client configuration file should define the LDAP server URI using the uri variable as ldap://host:port. If no port is specified, 389 will be used by default.
  • The distinguished name of the search base is defined by the variable base.
  • If server has TLS support, TLS_CACERT file_name specifies the file that contains certificates for all of the certificate authorities. During provisioning, zCX copies the certificate file to the directory /etc/ldap and renames it to ldap-ca.crt. Therefore, the TLS_CACERT setting in the LDAP configuration file should be /etc/ldap/ldap-ca.crt.
  • The LDAP group to which log in access will be restricted is defined by the variables pam_groupdn and pam_member_attribute
  • The TLS_CACERT file must be in EBCDIC code page on z/OS. This file must be located on the same z/OS system as the zCX instance and must be in a UNIX file system accessible to the provisioning user through z/OSMF.

BINDDN <distinguished_name> specifies a user name with read and search access to the LDAP directory. The BINDDN parameter specifies the distinguished name (DN) to use when performing LDAP operations. If not specified, LDAP operations are performed using an anonymous identity or the identity of each zCX user that is allowed to log in using LDAP authentication. Only specify BINDDN if the LDAP server does not permit anonymous search for users in the directory. Most LDAP servers allow anonymous access by default. If you do need to use the BINDDN parameter, create a read-only account with read and search access on LDAP server. Use the newly created distinguished_name in the ldap.conf file.

BINDPW specifies the password to use when performing LDAP operations. This is typically used in conjunction with the BINDDN parameter. The password is in clear text in the ldap.conf file.

Only one LDAP group can be given access to a zCX instance. If a user needs access to more than one zCX instance, that user should be added to each corresponding group.

Example LDAP configuration file

The following is a basic example of how to define an LDAP client configuration file:
# Here is a sample ldap.conf file to allow a zCX appliance to authenticate users
# by using an LDAP server.
 
uri ldap://hostname
base dc=example,dc=com
ldap_version 3
 
# LDAP searches will be performed using the anonymous identity by default
 
# The file that contains certificates for all of the certificate authorities
tls_cacertfile /etc/ldap/ldap-ca.crt
# The LDAP group to allow access to this zCX instance
pam_groupdn cn=zcxldapgroup,ou=Groups,dc=example,dc=com
pam_member_attribute memberUid
The above sample restricts access to members of LDAP posixGroup zcxldapgroup, whose members are specified in the memberUid attribute. See additional attributes you can define in an LDAP configuration file: http://manpages.ubuntu.com/manpages/trusty/man5/pam_ldap.5.html

Example of setting IPv6 LDAP support

Here is a sample ldap.conf file to allow a zCX instance to authenticate users by using an LDAP server with an IPv6 address. If IPv6 address is used, it should be in square brackets. LDAP searches will be performed using the anonymous identity by default. The file that contains certificates for all of the certificate authorities is tls_cacert /etc/ldap/ldap-ca.crt.
uri ldap://[IPv6_address]:port
base dc=example,dc=com
ldap_version 3

Example of LDAP user management for zCX

This example demonstrates how to set up a posixGroups and posixAccounts for LDAP user management. This scenario is based on OpenLDAP.

Assume you have two zCX instances (zcxappliance1 and zcxappliance2) and three zCX users (zcxuser1, zcxuser2, and zcxadmin). You want to give zcxuser1 access to only zcxappliance1 and zcxuser2 access to only zcxappliance2. You want to give zcxadmin access to both zcxappliance1 and zcxappliance2.

The OpenLDAP tree structure for this scenario is as follows:
  1. dc=example,dc=com
    1. ou=Groups
      1. cn=zcxgroup1
      2. cn=zcxgroup2
    2. ou=People
      1. uid=zcxadmin
      2. uid=zcxuser1
      3. uid=zcxuser2
Here, zcxgroup1 and zcxgroup2 are posixGroups set up for access to zcxappliance1 and zcxappliance2, respectively. User zcxuser1 will be a member of zcxgroup1 and zcxuser2 will be a member of zcxgroup2. Since zcxadmin should be allowed to access both zcxappliance1 and zcxappliance2, zcxadmin will be a member of both zcxgroup1 and zcxgroup2.
Below is an example of an LDAP entry of object class posixGroup that adds zcxuser1 and zcxadmin to zcxgroup1:
dn: cn=zcxgroup1,ou=groups,dc=example,dc=com
objectClass: top
objectClass: posixGroup
cn: zcxgroup1
gidNumber: 1001
memberUid: zcxuser1
memberUid: zcxadmin
  • gidNumber: the Linux GID number of the group. All gidNumbers must be unique and in the range of 1,010-999,999.
  • cn: the name of the group
  • memberUid: identifies users of the group
Similarly, zcxgroup2 can be defined as:
dn: cn=zcxgroup2,ou=groups,dc=example,dc=com
objectClass: top
objectClass: posixGroup
cn: zcxgroup2
gidNumber: 1002
memberUid: zcxuser2
memberUid: zcxadmin
The entries above can be added to the LDAP server by saving the group definitions as LDIF files and using the ldapadd command.
The posixAccount entries for each user can be similarly created and added. Here is an example definition for zcxuser1:
dn: uid=zcxuser1,ou=People, dc=example,dc=com
objectClass: shadowAccount
objectClass: posixAccount
objectClass: inetOrgPerson
cn: zcxuser1
gidNumber: 1001
homeDirectory: /home/zcxuser1
sn: zcxuser1
uid: zcxuser1
uidNumber: 2001
displayName: zcxuser1
gecos: zcxuser1
givenName: zcxuser1
loginShell: /bin/bash
  • uid: user's Linux login ID
  • uidNumber: the user's Linux UID. All uidNumbers must be unique and in the range of 1,010-999,999.
  • gidNumber: the primary group of this user
  • homeDirectory: the location of the home directory that will be created the first time the user logs in to the zCX instance.
The entries above can be added to the LDAP server by saving the user definitions as LDIF files and using the ldapadd command. Use the ldappasswd command to set the password for an LDAP user.

Restricting LDAP login by group

All users defined in the search based on an LDAP configuration file will have access to a zCX instance unless otherwise defined by the pam_groupdn attribute. Continuing with the previous example, two lines can be added to the zcxappliance1 configuration file to allow only members of zcxgroup1 access:
pam_groupdn cn=zcxgroup1,ou=Groups,dc=example,dc=com
pam_member_attribute memberUid
Similarly, the following lines can be added to the zcxappliance2 configuration file to allow only the users of zcxgroup2 access:
pam_groupdn cn=zcxgroup2,ou=Groups,dc=example,dc=com
pam_member_attribute memberUid

IBM Tivoli Directory Server for z/OS

For more information, see the IBM Tivoli Directory Server for z/OS with RACF back-end in the IBM Documentation.