API requester TLS client authentication to a RESTful API endpoint

TLS client authentication can be used to secure communications between the IBM® z/OS® Connect server and the RESTful API endpoint.

zosConnect-2.0 Applies to zosConnect-2.0.

When a request is made to establish a TLS connection from the IBM z/OS Connect server to the API provider, an SSL handshake is initiated. The API provider requests a client certificate from the IBM z/OS Connect server, which in turn supplies the certificate.

To establish a TLS connection, an SSL handshake is initiated between the API requester and the RESTful API.
TLS client authentication, also known as mutual TLS authentication, requires the following preparation before an SSL handshake can take place.
  • The API provider's keystore must contain the certificate it uses to identify itself.
  • The Certificate Authority which issued the API provider's certificate, must be added to the IBM z/OS Connect server's truststore so that the IBM z/OS Connect server can trust the API provider.
  • The z/OS Connect server's keystore must contain a certificate to identify itself.
  • The Certificate Authority which issued the certificate for the IBM z/OS Connect server, must be added to the API provider's truststore so that the API provider can trust the IBM z/OS Connect server.

The API provider may additionally use the client certificate to establish an authenticated identity which is used to run the RESTful API.

Configuring z/OS Connect SSL elements for TLS client authentication

z/OS Connect TLS is configured by using elements in the server.xml configuration file. IBM z/OS Connect includes a default SSL configuration. This default configuration is typically customized to add your own keystores and truststores. The following excerpt from a server.xml configuration file that uses a SAF key ring shows an example of how to configure the TLS client authentication for the Watson RESTful API. 

<keyStore id="zosconnectKeyStore"
    fileBased="false"
    location="safkeyring:///Keyring.ZOSCONN"
    password="password"
    readOnly="true"
    type="JCERACFKS" />

<keyStore id="zosconnectTrustStore"
    fileBased="false"
    location="safkeyring:///Keyring.ZOSCONN"
    password="password"
    readOnly="true"
    type="JCERACFKS" />

<ssl id="zosconnectSSLConfig" keyStoreRef="zosconnectKeyStore"
      trustStoreRef="zosconnectTrustStore"/>

<zosconnect_endpointConnection id="watson-api-explorer"  
      host="https://watson-api-explorer.mybluemix.net"
      port="443"            
      sslCertsRef="zosconnectSSLConfig"/>
To configure z/OS Connect to use a TLS connection to the API provider, you must configure the zosconnect_endpointConnection element with
  • a host, specifying the https protocol
  • a port, specifying the HTTPS port for the API provider
  • a sslCertsRef, to reference the SSL configuration. This references the keystore and truststore that store the certificates. If this attribute is not specified, the SSL configuration referenced by the sslDefault element is used.

If the z/OS Connect server's keystore, for example, zosconnectKeyStore, contains more than one private key, you must specify the clientKeyAlias attribute on the ssl element. This must be the alias of the certificate in the keystore that contains the key to be used during the TLS handshake.

For more information about the elements shown in the example above, see zosConnect-2.0 Configuration elements in the Reference section.

By default the z/OS Connect server verifies the common name (CN) of the RESTful API personal certificate. This check can be disabled by setting the disableCNCheck attribute of the webTarget element. For more information. see Opens in new window.JAX-RS Client Properties (webTarget) in the WebSphere Application Server for z/OS Liberty documentation.