API requester client certificate authentication to IBM z/OS Connect

Client certificate authentication can be used between the CICS, IMS or a z/OS application and the z/OS Connect server.

zosConnect-2.0 Applies to zosConnect-2.0.

Client certificate authentication uses information that is provided in the CICS, IMS or the z/OS application's TLS certificate to map to an associated user ID. It also provides all of the normal benefits that are associated with a secure TLS connection.

Client certificate authentication requires the CICS, IMS or a z/OS application to send a certificate on the request.
  • For IMS or a z/OS application, an AT-TLS outbound policy must be configured.
  • For CICS, either an AT-TLS outbound policy can be configured, or CICS native TLS support can be used.
Note: If you configure an AT-TLS inbound policy to secure the connection into a z/OS Connect server, then client certificate authentication cannot be used.
Figure 1 shows client certificate authentication between a CICS, IMS, or z/OS application, and IBM z/OS Connect.
Figure 1. Client certificate authentication
Diagram shows how the communication stub passes the TLS client certificate between the z/OS application and the API requester in IBM z/OS Connect.
When TLS client authentication is required by the IBM z/OS Connect server, the IBM z/OS Connect server must be configured with an HTTPS port. For each HTTPS connection, the z/OS Connect server asks the CICS, IMS or the z/OS application to provide its certificate and validates the chain of trust by using its truststore. That is, it validates that the client certificate issuer is trusted. This is standard TLS behavior and if the CICS, IMS or the z/OS application certificate is successfully validated, the connection can be established to the IBM z/OS Connect server.

Mapping the client certificate to a user ID

To authenticate to the IBM z/OS Connect server, the CICS, IMS or the z/OS application certificate must also be mapped to a user ID in the user registry. If the certificate is successfully mapped to a user ID, then that user ID is set as the authenticated user.

Typically a System Authorization Facility (SAF) registry is used with IBM z/OS Connect, although IBM z/OS Connect also supports Basic user registry and Lightweight Directory Access Protocol (LDAP) user registry. For more information about configuring the user registries, see User registries.

If using a SAF registry, a DIGTCERT profile is generated from the information in the certificate, such as the certificate's serial number and the issuer's distinguished name. The profile must be associated with a SAF user ID. Client certificates can be associated with a RACF user ID in two ways:
  • Use the RACDCERT MAP command to define a certificate name filter, which is also called a user ID mapping. This maps the certificate subject's distinguished name (DN) to a RACF user ID. Certificate name filtering supports generic filters allowing multiple certificates to be associated with a single RACF user ID.
  • Use the RACDCERT ADD command to add the certificate into RACF and specify the user ID it is to be associated with.
For more information, see A launch icon to indicate a link opens a new tab or window.RACDCERT ADD (add certificate) and A launch icon to indicate a link opens a new tab or window.RACDCERT MAP in the z/OS documentation.

If using a basic registry, the user identity is the common name (CN) from the distinguished name (DN) of the certificate. For more information about using client authentication with a basic registry, see A launch icon to indicate a link opens a new tab or window.Basic certificate map mode in the WebSphere Application Server for z/OS Liberty documentation.

If using an LDAP registry, the DN from the client certificate must be in the LDAP registry. For more information about using client authentication with LDAP, see A launch icon to indicate a link opens a new tab or window.LDAP certificate map mode in the WebSphere Application Server for z/OS Liberty documentation.

Configuring CICS, IMS or a z/OS application for client certificate authentication

The CICS, IMS or z/OS application must first be configured to use a TLS connection with TLS client authentication enabled to the z/OS Connect server. Work with your z/OS Connect security administrator to agree the distinguished names of the client certificates to be sent on the requests, and the RACF user IDs they should be mapped to.

For more information, see How to configure TLS from CICS or How to configure AT-TLS from an IMS or z/OS application.

Configuring IBM z/OS Connect for client certificate authentication

The IBM z/OS Connect server is configured for client certificate authentication using an SSL configuration. The ssl element in the server.xml configuration file must set attribute clientAuthentication to true to request the client to provide a certificate.

The SSL configuration associated with the HTTP endpoint element affects all requests to the HTTPS port. If some of your requests do not require client authentication then you can configure multiple ports to allow for different SSL configurations.