zCX user administration
This chapter describes how to configure a zCX instance to use an existing LDAP server for authentication. LDAP authentication can be preferable to local user authentication because it provides an easy way to create identical user and group configurations across multiple instances. Modifications to users and groups are also much simpler when you use LDAP because changes to the LDAP architecture are immediately propagated to the authentication scheme of the instances.
When LDAP authentication is enabled for an instance, local user management and public key authentication are disabled.
All servers that abide by the RFC 4511 protocol (https://tools.ietf.org/html/rfc4511) are candidates for authentication of zCX. Setting up an LDAP server from scratch is beyond the scope of this chapter. For information about setting up a server see:
https://www-01.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosv2r4sc236788/$file/glpa200_v2r4.pdf
The following user administration details are covered in this chapter:
9.1 Local user management
After provisioning, the zCX instance Docker administrator is responsible for managing the Docker daemon and Docker users within the zCX appliance instance. The user information for the Docker administrator must be given during provisioning so that the user ID can be configured to manage the Docker daemon in the zCX instance. The Docker administrator does not necessarily need to be a z/OS user or zCX appliance administrator. How to configure and set up the Docker admin user is described in section 4.2.6, “Create SSH Keys” on page 51 .
9.1.1 Adding Docker users
Docker users have the ability to run Docker commands only. This condition exists because they are added to the Docker user group. Therefore, they cannot create or modify other Docker users.
Adding Docker users
To create a new Docker user with user name username and add the new user to the existing group Docker, the administrator runs the command in Example 9-1.
Example 9-1 Add a new docker user
admin@1edc6a418cd8:~$ sudo adduser --ingroup docker local-user
Adding user `local-user' ...
Adding new user `local-user' (1002) with group `docker' ...
Creating home directory `/home/local-user' ...
Copying files from `/etc/skel' ...
Enter new UNIX password: <password>
Retype new UNIX password: <password>
passwd: password updated successfully
Changing the user information for local-user
Enter the new value, or press ENTER for the default
Full Name []: <details>
Room Number []: <details>
Work Phone []: <details>
Home Phone []: <details>
Other []: <details>
Is the information correct? [Y/n] Y
While creating the users, you must define the password for the user. After the password is set, further details can be given, or the default values can be used. Confirmation at the end is required with a yes (Y) entry.
To confirm that the user has been created and the users home directory is created, issue the ls -l /home command as shown in Example 9-2.
Example 9-2 Display the home directories
admin@1edc6a418cd8:~$ ls -l /home
total 0
drwxr-xr-x 1 admin admin 186 Sep 17 20:27 admin
drwxr-xr-x 1 local-user docker 54 Sep 17 20:27 local-user
The administrator can force a new Docker user to change the user password at login by running the following command: sudo passwd -e local-user
Example 9-3 Force a password change during first logon
admin@1edc6a418cd8:~$ sudo passwd -e local-user
passwd: password expiry information changed.
After it is created, the new Docker user can SSH into the container and use Docker with the following command:
ssh [email protected] -p 8022
This command results in a logon on the local zCX instance.
Example 9-4 SSH Logon with the newly created user
admin@1edc6a418cd8:~$ ssh [email protected] -p 8022
[email protected]'s password: <current_password>
You are required to change your password immediately (root enforced)
 
Welcome to the IBM z/OS Container Extensions (IBM zCX) shell that provides access to Docker commands.
For more information on how to use this shell to execute Docker commands refer to "IBM z/OS Container Extensions Guide".
WARNING: Your password has expired.
You must change your password now and login again!
Changing password for local-user.
(current) UNIX password: <current_password>
Enter new UNIX password: <new_password>
Retype new UNIX password: <new_password>
passwd: password updated successfully
If this is the first time that you are logging on to the machine, you must confirm the ssh key with YES. Afterward, you must log on with the password that was initially set as shown in Example 9-1 on page 220. At that point, you are forced to change it to a new password.
Adding Docker administrators
You create additional Docker administrators by adding Docker users to the Groups ‘Docker’ and giving them sudo access. The only abilities that the Docker Admin has beyond that of a standard Docker User is to add, modify, and delete other Users and Admins. An administrator can create additional Docker administrators by using the command shown in Example 9-5.
Example 9-5 Add a new docker administrator
admin@1edc6a418cd8:~$ sudo adduser local-admin
Adding user `local-admin' ...
Adding new group `local-admin' (1002) ...
Adding new user `local-admin' (1003) with group `local-admin' ...
Creating home directory `/home/local-admin' ...
Copying files from `/etc/skel' ...
Enter new UNIX password: <password>
Retype new UNIX password: <password>
passwd: password updated successfully
Changing the user information for local-admin
Enter the new value, or press ENTER for the default
Full Name []: <details>
Room Number []: <details>
Work Phone []: <details>
Home Phone []: <details>
Other []: <details>
Is the information correct? [Y/n] y
While creating the users, you must define the password for the user. When the password is set, further details can be given or the default values can be used. Confirmation at the end is required with Y.
Then, add the user to the groups docker and sudo by using the commands shown in Example 9-6.
Example 9-6 Modify admin user to be part of docker and sudo group
admin@1edc6a418cd8:~$ sudo adduser local-admin docker
admin@1edc6a418cd8:~$ sudo adduser local-admin sudo
If needed, the administrator can then switch to the new user by using the command shown in Example 9-7 on page 222
Example 9-7 Switch the user
admin@1edc6a418cd8:~$ su local-admin
Password:
Sudo only permits specific User Management functions. See additional documentation for details.
 
 
local-admin@1edc6a418cd8:/home/admin$
To verify the groups that a user is connected to, you can just issue the groups command.
Example 9-8 Display the groups a user is connected to
local-admin@1edc6a418cd8:/home/admin$ groups
local-admin sudo docker
9.2 Configuring zCX to use an LDAP server
In this section, we discuss how to configure zCX to use an LDAP server.
9.2.1 LDAP server configuration
When LDAP authentication is enabled, the zCX instance queries the configured search base for all posixAccount and posixGroup entries that match any specified filters. Then, it allows those users with posixAccount entries to log in to the zCX instance by using those entries, uid and userPassword. Therefore, it is important to verify that all users who should be able to authenticate have an entry in the LDAP configuration that includes a posixAccount objectClass defined as follows:
objectClass: posixAccount
The zCX instance respects all required and optional parameters of the posixAccount object class. It is recommended that the optional loginShell attribute be specified (Bourne shell is default). For more information about required and optional fields see:
https://ldapwiki.com/wiki/PosixAccount
Figure 9-1 illustrates an example LDAP directory tree that contains posixAccount and posixGroup entries. The remaining examples in this chapter are based on this directory tree.
Figure 9-1 Example LDAP architecture
Notice the following aspects of Figure 9-1:
•There are posix accounts defined: zcx_user_1, zcx_user_2, zcx_admin.
•Two posix groups are defined: zcx_group_1, zcx_group_2
•User zcx_admin is a member of both groups, zcx_user_1 is a member of zcx_group_1 and zcx_user_2 is a member of zcx_group_2
•A single groupOfUniqueNames is defined called auth_group, which contains zcx_admin and zcx_user_2. This is used in Example 9-9 on page 223 to enable group-based authentication. This approach is mandatory at the time of this writing, because posixGroup entries are not valid candidates for the “memberof” function for pam filters.
Each of the three users that are created with their own home directories and are started when the bash shell runs.
To create such an LDAP directory tree, ldapadd commands can be issued to insert the seven ldif files, which are shown in Example 9-9 through Example 9-15.
Example 9-9 Creation of “groups” organizational unit: groups.ldif
dn: ou=groups,dc=example,dc=org
objectclass: organizationalunit
ou: groups
Example 9-10 Creation of “auth_group” group of unique names : auth_group.ldif
dn: cn=auth_group,dc=example,dc=org
objectClass: top
objectClass: groupOfUniqueNames
cn: auth_group
uniqueMember: zcx_user_2,dc=example,dc=org
uniqueMember: zcx_admin,dc=example,dc=org
Example 9-11 Creation of “zcx_group_1” posixGroup: zcx_group_1.ldif
dn: cn=zcx_group_1,ou=groups,dc=example,dc=org
objectClass: top
objectClass: posixGroup
cn: zcx_group_1
gidNumber: 2001
memberUid: zcx_user_1
memberUid: zcx_admin
Example 9-12 Creation of “zcx_group_2” posixGroup: zcx_group_2.ldif
dn: cn=zcx_group_2,ou=groups,dc=example,dc=org
objectClass: top
objectClass: posixGroup
cn: zcx_group_2
gidNumber: 2002
memberUid: zcx_user_2
memberUid: zcx_admin
Example 9-13 Creation of “zcx_user_1” posixAccount: zcx_user_1.ldif
dn: uid=zcx_user_1,dc=example,dc=org
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
userPassword: pass
cn: zcx_user_1
sn: zcx_user_1
uid: zcx_user_1
uidNumber: 1001
gidNumber: 2001
homedirectory: /home/zcx_user_1
loginShell: /bin/bash
Example 9-14 Creation of “zcx_user_2.ldif” posixAccount: zcx_user_2.ldif
dn: uid=zcx_user_2,dc=example,dc=org
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
userPassword: pass
cn: zcx_user_2
sn: zcx_user_2
uid: zcx_user_2
uidNumber: 1002
gidNumber: 2002
homedirectory: /home/zcx_user_2
loginShell: /bin/bash
Example 9-15 Creation of “zcx_admin” posixAccount: zcx_admin.ldif
dn: uid=zcx_admin,dc=example,dc=org
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
userPassword: pass
cn: zcx_admin
sn: zcx_admin
uid: zcx_admin
uidNumber: 1003
gidNumber: 2001
homedirectory: /home/zcx_admin
loginShell: /bin/bash
9.2.2 Creating the LDAP configuration file
Creation of an LDAP configuration file is an integral part of enabling a connection to the LDAP server. The file describes where the server can be found. And the file defines the search domain from which user and group information should be retrieved. For a full list of options see the following web page:
This configuration is based entirely on how each LDAP server is configured, but some of the more common options are as follows:
•URI - The full URI of the LDAP server, starting with ldap:// for non-ssl enabled connections or ldaps:// enabled connections, followed by the hostname and an optional port (defaults to 389 for non-ssl and 636 for ssl)
•BASE - The distinguished name of the search base in which to look for posixAccount entries.
•BINDDN - The fully distinguished name of the bind user to use for authentication, this is required for LDAP servers that do not allow anonymous binds.
•BINDPW - The password of the bind user, which is required for LDAP servers that do not allow for anonymous binds.
•TLS_CACERTFILE - Location of the CA Certificate that signed the LDAP servers certificates. This location refers to a path on the zCX instance, not on the provisioning server. For instances with TLS enabled, this value is always /etc/ldap/ldap-ca.crt regardless of the original name of the provided CA Certificate file.
•SSL - Indicates whether SSL should be enabled for the connection to the LDAP server. For instances that are configured to use TLS without SSL, set this value to starttls.
•PAM _FILTER - Allows for additional filtering of entries that appear within the search base. An example of a PAM_FILTER used to limit access to a specific group within the search base can be found in Example 9-16. For more information on creating PAM filters see:
Building on the structure that is defined in Figure 9-1 on page 223, assume that the LDAP server is running on IP 129.40.23.84, uses the default port of 389, and that SSL is not enabled. TLS authentication is enabled for this instance. The configuration shown in Example 9-16 on page 225 defines properties that connect to the example server and allow access to the ZCX_USER_2 and ZCX_ADMIN user by defining a PAM_FILTER to allow access only to users in the AUTH_GROUP.
Example 9-16 Sample configuration for a PAM_FILTER
# IP and port of the LDAP server
URI ldap://129.40.23.84:389/
# Distinguished name of base search path
BASE dc=example,dc=org
# Distinguished name of bind user for authentication
binddn cn=admin,dc=example,dc=org
# Location of CA Certificate. This value is always
TLS_CACERTFILE /etc/ldap/ldap-ca.crt
# SSL Configuration, not using SSL in this scenario
SSL starttls
# Password of bind user
bindpw admin
# Restrict access to posixaccount entries in the search path that are members of AUTH_GROUP. The group specified as the target of “memberof” cannot be a posixGroup, hence the creation of specific groupOfUniqueNames entry that contains the users that should be filtered.
pam_filter &(objectclass=posixaccount)(memberof=cn=auth_group,ou=groups,dc=example,dc=org)
9.2.3 Enabling LDAP server authentication through z/OSMF Workflows
LDAP server authentication can be optionally enabled in either the provision z/OSMF workflow for new instances or in the reconfigure z/OSMF workflow for instances that have already been provisioned. For more information about using workflows for zCX configuration, see Chapter 4, “Provisioning and managing your first z/OS Container” on page 47. In either type of workflow, there are four options that must be considered and configured. Table 9-1 describes these fields.
Table 9-1 LDAP server parameters for z/OSMF workflow
Field Name
Description
Required
Enable LDAP Authentication
Whether LDAP authentication should be used for this instance instead of local user authentication. This value should be set to TRUE.
Yes
LDAP Client Configuration File Path
The absolute path to the LDAP client configuration file on the provisioning system, this file must be accessible to the provisioning user. This file describes:
•How the LDAP server can be reached.
•The search base that users should be queried from.
•Security for connections that are made to the server.
An example of a simple configuration is provided in Appendix 9.2.1, “LDAP server configuration” on page 222. For a full list of options see:
Yes
Enable LDAP Client TLS Authentication
Whether TLS authentication should be enabled for the LDAP client connection:
•For LDAP servers with TLS enabled this value should be set to TRUE.
•Otherwise, this should be set to FALSE.
Yes
LDAP Client TLS CA Certificate
The absolute path on the provisioning system to the TLS CA Certificate that signed the LDAP server certificate. This file must be accessible to the provisioning user and encoded in EBCDIC. This file should be provided by your LDAP server administrator.
This value is only required when Client TLS Authentication is enabled
Each of these four parameters is located in the”Gather IBM zCX appliance instance properties” step as shown in Figure 9-2 on page 227 for the provision workflow and in the same step as shown in Figure 9-3 on page 227 for the reconfigure workflow.
Figure 9-2 Gather IBM zCX appliance instance properties step in provision workflow
 
Figure 9-3 Gather IBM zCX appliance instance properties step in reconfigure workflow
After you reach the “Gather IBM zCX appliance instance properties” step of the provision workflow, navigate to the “zCX Docker User Management Configuration” substep as shown in Figure 9-4 on page 228. Dummy values have been filled in for the Docker Admin User ID and Docker Admin SSH Key fields. These dummy values serve to remind you that the Docker admin user will be disabled when LDAP Authentication is enabled.
Figure 9-4 zCX Docker User Management Configuration for provision workflow
For the reconfigure workflow, navigate to the “zCX Docker User Management Configuration” substep as shown in Figure 9-5.
Figure 9-5 zCX Docker User Management Configuration for configure workflow
9.3 Resources on the provisioning server and verifying that LDAP is enabled
This section continues with the example in Example 9-2 on page 227. The zCX instance is configured to use the previously defined ldap.conf and to enable TLS authentication. The zCX instance runs with IP 129.40.23.85.
The ldap.conf and ca.crt files must be placed on the provisioning system and must be accessible to the provisioning user, which is ZCXPRV9 as seen in Figure 9-6. The ca.crt file must be encoded in EBCDIC.
Figure 9-6 LDAP configuration directory on provisioning system
After completing the provisioning or reconfigure workflow, you can verify that LDAP server authentication is enabled by attempting to log in with the zcx_admin user as shown in Figure 9-7.
Figure 9-7 Verifying zcx_admin user access
At this point, the admin account that was configured during provisioning no longer exists. You can confirm this fact by attempting to ssh in to the admin account. A password prompt like the one in Figure 9-8 is displayed.
Figure 9-8 Instance admin account disabled
 
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.222.115.120