API requester client certificate authentication to IBM z/OS Connect

zosConnect-3.0 Applies to zosConnect-3.0.

Client certificate authentication can be used between a z/OS application and the IBM z/OS Connect Server when no inbound AT-TLS policy is configured so that the request is received by an HTTPS port in the z/OS Connect Server.

For more information about supported AT-TLS configurations, see API requester confidentiality and integrity for zosConnect-3.0.

Client certificate authentication uses information that is provided in 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 z/OS application to send a certificate on the request.
  • For IMS and z/OS applications, 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 because z/OS Connect is an unaware of the AT-TLS application and therefore does not have access to the partner certificate.
Figure 1 shows client certificate authentication between a z/OS application, and z/OS Connect.
Figure 1. Client certificate authentication
Diagram shows how the Host API passes the TLS client certificate between the z/OS application and the API requester in z/OS Connect.
When TLS client authentication is required by the z/OS Connect Server, the z/OS Connect Server must be configured with an HTTPS port. For each HTTPS connection, the z/OS Connect Server asks 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 z/OS application certificate is successfully validated, the connection can be established to the z/OS Connect Server.

Mapping the client certificate to a user ID

To authenticate to the z/OS Connect Server, 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 z/OS Connect, although 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. Use one of the following two methods to associate the client certificates with a RACF user ID:
  • 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. This is the typical method that is used because it does not add the client certificate into the RACF database.
  • Use the RACDCERT ADD command to add the certificate into the RACF database 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 (create mapping) in the z/OS Security Server RACF Command Language Reference.

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 a z/OS application for client certificate authentication

The z/OS application must first be configured to use a TLS connection with TLS client authentication that is 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 an AT-TLS connection from CICS for z/OS Connect zosConnect-3.0 or How to configure an AT-TLS connection from IMS or z/OS applications for z/OS Connect zosConnect-3.0.

Configuring z/OS Connect for client certificate authentication

The z/OS Connect Server is configured for client certificate authentication by 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 that is 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.