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 IBM z/OS Connect resources.
This task is applicable when IBM z/OS Connect is used as an API requester.
Before you begin
- 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® 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 an AT-TLS connection from CICS
- 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 MAPcommand. For more information about the
RACDCERTcommands and the authorizations that are required, see RACDCERT (Manage RACF digital certificates) in the z/OS Security Server RACF Command Language Reference.
- You must have write access to the server.xml configuration file.
About this task
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 IBM z/OS Connect to perform authentication using a TLS client certificate.
During authentication, IBM z/OS Connect will call RACF to perform the mapping resulting in the mapped RACF user ID being the authenticated user ID.
appSecurity-2.0feature is configured.
Activate the RACF DIGTNMAP class to allow certifcate
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:
EMPLOY1is the RACF user ID to which the client certificate is to be mapped.
CN=myClient.host.com.O=IBM.C=USis the subject distinguished name filter which 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.
ClientCertEMPLOY1is a label for the mapping.
RACDCERT MAPcommand, see RACDCERT MAP (Create mapping) in the z/OS Security Server RACF Command Language Reference.
- Refresh the DIGTNMAP RACF class. For the changes to take effect. enter the following RACF command:SETROPTS RACLIST(DIGTNMAP) REFRESH
- Ensure that the server is configured to require authentication for the request by
<featureManager> <feature>appSecurity-2.0</feature> </featureManager>
- Configure the server to perform authentication using the TLS
client certificate. Set CLIENT_CERT as the authentication method by adding the following element to the configuration file:
<webAppSecurity overrideHttpAuthMethod="CLIENT_CERT"/>Warning: Setting this authentication method means that an authentication certificate is expected for all requests.
- Start, or restart IBM z/OS Connect if it was already running, to pick up the changes that are made to the RACF class profiles.
The TLS client certificate is mapped to a RACF user ID, and is authorized to access IBM z/OS Connect.