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 provider.
Before you begin
- You should be familiar with the information in API provider 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 REST client 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.
- 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 Security Server RACF Command Language Reference.
- 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 IBM z/OS Connect server to require authentication, by
setting the attribute requireAuth="true"
.
During authentication, the IBM z/OS Connect server will call 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 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:
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 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.
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 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.
This can be set at various scopes:
- To require authentication globally for the server, set
requireAuth="true"
on
the zosconnect_zosConnectManager
element in the server.xml
configuration file. For
example,<zosconnect_zosConnectManager requireAuth="true"... />
- To require authentication for a specific API, which takes precedence over the global server
setting, set
requireAuth="true"
on the zosConnectAPI
element in
the server.xml configuration file. For example,
<zosconnect_zosConnectAPIs>
<zosConnectAPI name="Api1"
requireAuth="true"/>
</zosconnect_zosConnectAPIs>
- To require authentication for a specific service, which takes precedence over the global server
setting, set
requireAuth="true"
on the service
element in the
server.xml configuration file. For
example,<zosconnect_services>
<service name="Service1"
requireAuth="true"/>
</zosconnect_services>
For more information about these elements see
Configuration elements
in the
Reference section.
- Assign the mapped RACF user ID to the
zosConnectAccess
role.
- Ensure 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
IBM 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 made to
the RACF class profiles.
Results
The TLS client certificate is mapped to a RACF user ID, and is authorized to access IBM 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.