Authorizing access to z/OS UNIX System Services

CICS® requires access to z/OS® UNIX System Services and to directories and files in the file system. CICS facilities that require this access include TCP/IP support, Java™ support, CICS Web support, and task-related user exits that are enabled with the OPENAPI option, including the task-related user exit of the CICS Db2® attachment facility.

Before you begin

You must set up z/OS UNIX System Services, as described in z/OS UNIX System Services Planning.

About this task

To satisfy a CICS region request for a z/OS UNIX function for the first time, RACF® does the following actions:

Verifies that the user (the CICS region user ID) is defined as a z/OS UNIX user.
Verifies that the user's current connect group is defined as a z/OS UNIX group.
Initializes the control blocks required for subsequent security checks.

Follow the steps listed to ensure that each CICS region meets the security requirements:

Choose a RACF group that all your CICS regions can use to access z/OS UNIX and give a z/OS UNIX group identifier (GID) to this RACF group.
Give a z/OS UNIX user identifier (UID) to each CICS region user ID.
Make sure that each CICS region user ID connects to the RACF group that you chose.
Set up a home directory on z/OS UNIX for each of your CICS regions.

The UID and GID are numbers that can be in the range 0 to 16 777 216. 0 is a superuser ID. Give some thought to naming conventions and to any existing UIDs and GIDs in your z/OS UNIX system. For information on how to manage the UIDs and GIDs for your z/OS UNIX system, see z/OS UNIX System Services Planning.

Note: If you are upgrading to z/OS 2.1.0 or above and have defined a BPX.DEFAULT.USER profile, please note that this is no longer supported. Instead you must define the BPX.UNIQUE.USER profile to enable the automatic assigning of UIDs and GIDs to users without an assigned OMVS segment. For more information, see Using the BPX.UNIQUE.USER profile instead of BPX.DEFAULT.USER in z/OS Migration.

To assign a z/OS UNIX UID and GID for your CICS regions and set up a home directory:

Procedure

Choose a RACF group that can be used by all your CICS regions. For example, you might use a RACF group that is defined as the default group of your CICS region user IDs, or you could set up a RACF group to be used only for access to z/OS UNIX System Services.
When you are setting up facilities such as Java support or CICS Web support, you might want to use this RACF group for giving file access permissions on z/OS UNIX, in which case the RACF group's z/OS UNIX group identifier (GID) is associated with these directories and files. This association means that the owner of these directories and files, and anyone who is not the owner but has to carry out operations with these files, must have this group as their group or one of their supplementary groups. The RACF Profiles explains how RACF groups work.
Choose a suitable z/OS UNIX group identifier (GID) for the RACF group, and assign the GID to the RACF group. To assign a GID, specify the GID value in the OMVS segment of the RACF group profile.
For example, if the RACF group is CICSTSAB, and the GID you want to assign is 9, use the command:
```
ALTGROUP CICSTSAB OMVS(GID(9))
```
Choose a suitable z/OS UNIX user identifier (UID) for each CICS region. Implementing security for z/OS UNIX files explains how the region user ID under which CICS runs is specified when CICS is run as a started task, as a started job, or as a job.
1. Assign your chosen UIDs to each of your CICS region user IDs. To assign UIDs, specify the UID value in the OMVS segment of the RACF user profile for each CICS region user ID.
2. Also specify the name of a home directory for each CICS region using the HOME option. The directory name format is /u/CICS region user ID.
CICS TS security tells you how to update a RACF user profile using the ALTUSER command.
For example, if the CICS region user ID is CICSHAA1, and the UID you want to assign is 2001, use the command:
```
ALTUSER CICSHAA1 OMVS(UID(2001) HOME('/u/cicshaa1'))
```
If you want to know about the other information that can be specified in an OMVS segment parameter in a user profile besides the UID and home directory, see z/OS Security Server RACF Command Language Reference. You can assign the same UID to more than one CICS region user ID. If all your CICS regions must use the same z/OS UNIX files (for example, the files required for Java support), you can give all the CICS regions the same UID, and then you can use that UID for giving file access permissions on z/OS UNIX. However, bear in mind these points:
1. The sharing of UIDs allows each CICS region to access all of the z/OS UNIX resources that the other CICS regions with that shared UID can access, and this level of access might not be appropriate in your system.
2. The sharing of UIDs is not normally suitable in a z/OS UNIX system.
3. If you do choose to share UIDs, the z/OS UNIX System Services parameter MAXPROCUSER limits the maximum number of processes that a single user (that is, with the same UID) can have concurrently active.
Set up each of the z/OS UNIX directories that you have specified as a home directory for one of your CICS regions.
Further information on each of these steps is provided in z/OS UNIX System Services Planning.
1. If you are not using an automount facility, use the mkdir command to create the z/OS UNIX directories.
  For example, issuing the UNIX command
```
mkdir /u/cicshaa1
```
  Creates the z/OS UNIX directory /u/cicshaa1. If you are using the TSO command, enclose the directory name in single quotation marks.
2. Whether or not you are using an automount facility, allocate a z/OS UNIX data set for each directory.
3. If you are not using an automount facility, mount the data set that you have allocated.
The z/OS UNIX data set that you allocate for a CICS region's home directory has a finite size. If a particular CICS region is using the home directory extensively, you might have to increase the amount of space that the region has available.
Verify that the permission defined for the /etc directory is set to 755, so that CICS can access the files. The /etc directory provides a symbolic link to the /SYSTEM/etc directory. The /SYSTEM/etc directory is created with a permission of 700, so you need to check that the /SYSTEM/etc directory permission is set to 755.
1. Check the permission set in the /SYSTEM/etc directory, from the Unix shell:
```
ls -ld /SYSTEM/etc
```
2. If the permission is not drwxr-xr-x, issue the following Unix shell command to set permission to 755:
```
chmod 755 /SYSTEM/etc
```
  If permission is not set to 755, you might receive a RACF error indicating that you have insufficient authority for CICS to access the files.
Make sure that each of your CICS region user IDs connects to the RACF group to which you assigned a z/OS UNIX group identifier (GID). If your CICS region user IDs connect to more than one RACF group, a RACF list of groups must be active in your system.

What to do next

Your CICS regions now have access to z/OS UNIX System Services. When you set up facilities such as Java support or CICS Web support, use the UIDs or GIDs to give the CICS regions permission to access directories and files on z/OS UNIX.

To check the UID and GID details for a user, use the id command in the UNIX environment. For example, issuing the id command for our example CICS region user ID CICSHAA1 gives the following result:

uid=2001(CICSHAA1) gid=9(CICSTSAB)

For more general information about RACF facilities for controlling access to z/OS UNIX System Services, see z/OS Security Server RACF Security Administrator's Guide.