How to configure client certificate authentication with RACF

Configure a IBM® z/OS® Connect Server to perform authentication of the identity in a TLS client certificate, mapping the certificate to a RACF® user ID, and then granting that user ID authority to access z/OS Connect resources.

zosConnect-2.0 Applies to zosConnect-2.0.

This task is applicable when z/OS Connect is used as an API requester.

Before you begin

You should be familiar with the information in API requester authentication and identification.
You must have completed the task How to activate and configure the SAF user registry to configure the IBM z/OS Connect Server to use z/OS authorized services and a SAF user registry.
You must have configured a TLS connection between the CICS, IMS or a z/OS application, and the IBM z/OS Connect Server with TLS client authentication enabled. For example, by completing the steps in the task How to configure TLS with RACF key rings, and How to configure TLS from CICS or How to configure AT-TLS from an IMS or z/OS application.
You need to know the subject value of the client certificate to be mapped.
You need to know the user ID to which the TLS client certificate will be mapped, and this user ID must exist and have an OMVS segment.
You must have authorization to issue the RACDCERT MAP command. For more information about the RACDCERT commands and the authorizations that are required, see RACDCERT (Manage RACF digital certificates) in the z/OS documentation.
You must have write access to the server.xml configuration file.

About this task

This task assumes that RACF is used as security manager. If you are using an alternative External Security Manager, refer to the appropriate product documentation for the equivalent commands.

You use RACF certificate name filtering, also called user ID mapping, to map the TLS client certificate to a RACF user ID. You then configure the server to require authentication, by setting the attribute z/OS ConnectrequireAuth="true".

During authentication, the z/OS Connect Server calls RACF to perform the mapping resulting in the mapped RACF user ID being the authenticated user ID.

Procedure

Activate the RACF DIGTNMAP class to allow certificate name filters to be created or changed.
Enter the following RACF command:
```
SETROPTS CLASSACT(DIGTNMAP) RACLIST(DIGTNMAP)
```
Map the TLS client certificate to a RACF user ID.
Enter the following command to use RACF certificate name filtering to map the client certificate to a RACF user ID.
```
RACDCERT MAP ID(EMPLOY1) SDNFILTER('CN=myClient.host.com.O=IBM.C=US') WITHLABEL('ClientCertEMPLOY1')
```
The command uses the following values:
- EMPLOY1 is the RACF user ID to which the client certificate is to be mapped.
- CN=myClient.host.com.O=IBM.C=US is the subject distinguished name filter that corresponds to the client certificate subject's distinguished name value of CN=myClient.host.com, O=IBM, C=US. The syntax of the SDNFILTER is significant. Use periods to separate the components of the distinguished name and remove any spaces between DN components.
- ClientCertEMPLOY1 is a label for the mapping.
For the full syntax of the RACDCERT MAP command, see RACDCERT MAP (Create mapping) in the z/OS.
Refresh the DIGTNMAP RACF class.
Enter the following RACF command for the changes to take effect:
```
SETROPTS RACLIST(DIGTNMAP) REFRESH
```
Ensure that the server is configured to require authentication for the request.
This can be set at various scopes in the server.xml configuration file:
- To require authentication globally for the server, set requireAuth="true" on the zosconnect_zosConnectManager element. For example,
```
<zosconnect_zosConnectManager requireAuth="true"... />
```
- To require authentication for all API requesters, which takes precedence over the global setting, set requireAuth="true" on the zosconnect_apiRequesters element. For example,
```
<zosconnect_apiRequesters requireAuth=“true”>
    <apiRequester ... />
</zosconnect_apiRequesters>
```
- To require authentication for a specific API requester that has the highest precedence set requireAuth="true" on the apiRequester element. For example,
```
<zosconnect_apiRequesters>
    <apiRequester name="Stock_Control" requireAuth="true"/>
 </zosconnect_apiRequesters>
```
Important: When the requireAuth attribute is specified at more than one scope, the value set on the apirequester element takes precedence over the value set on the zosconnect_apiRequesters element, which takes precedence over the value on the zosconnect_zosconnectManager element.
For more information about configuration elements, see zosConnect-2.0 Configuration elements in the Reference section.
Assign the mapped RACF user ID to the zosConnectAccess role.
Follow the instructions in the task How to configure the zosConnectAccess role with a SAF user registry.
Ensure that the Liberty profile angel process is running.
To use z/OS authorized services for SAF authentication and authorization, the Liberty profile angel process must be running for the server to connect to. In one of the prerequisite tasks listed in the Before you begin section, you created a started task to run the Liberty angel process and granted permission for the z/OS Connect Server to access it.
To start the angel process, start the associated started task. Enter the following MVS command from SDSF,
```
/S BAQZANGL
```
For more information about starting the angel process and checking that it started successfully, see Start the Angel process as a started task in Configuring the Liberty Angel process and z/OS authorized services.
Start, or restart the server if it was already running, to pick up the changes that are made to the RACF class profiles.

Results

The TLS client certificate is mapped to a RACF user ID, and is authorized to access z/OS Connect.

What to do next

You might now be interested in configuring more specific authorization. See the task How to configure authorization levels with a SAF user registry.