Configuring client certificates for server connections

Generate a client certificate and configure the Eclipse preferences to send the certificate from the API toolkit to the z/OS® Connect Server. Import the client certificate into the server truststore.

Before you begin

zosConnect-2.0 Applies to zosConnect-2.0.

If SSL is enabled on the z/OS Connect Server, and a trusted client certificate is not sent in for authentication, an HTTP 403 Forbidden error is returned when connecting to the server.

Note: The embedded Swagger UI supports only basic authentication. Client authentication is not supported.

To connect to the server from the API toolkit, generate a client certificate first and import it into the truststore on the server.

Generate your client certificate.
This certificate is sent to the server for authentication. Use a tool such as keytool to create a keystore and then export the client certificate from the keystore. The following example shows the keytool command to create a keystore called myclient.keystore.p12:
```
keytool -genkey -alias myclient.cert -dname "CN=API editor client Keystore, OU=IBM Systems z, O=IBM, C=US" -keyalg RSA -keypass mypassword -storepass mypassword -storetype PKCS12 -keystore <path_to>/myclient.keystore.p12
```
Then, export the client certificate, myclient.cert.cer from the client keystore:
```
keytool -export -alias myclient.cert -storepass mypassword -storetype PKCS12 -file <path_to>/myclient.cert.cer -keystore <path_to>/myclient.keystore.p12
```
Transfer the client certificate to a location accessible to the z/OS Connect Server.
On the z/OS Connect Server, import the client certificate into the server truststore.
The following example shows the keytool command to import the client certificate into the server truststore.
```
keytool -import -v -trustclientcerts -alias apieditor.client -file myclient.cert.cer -keystore "<path_to>\server.truststore.p12" -keypass mypassword -storepass mypassword -storetype PKCS12
```
Modify the server.xml file to ensure that the following information is specified.
- If the z/OS Connect Server is configured to require client certificate authentication and TLS client authentication to provide confidentiality and integrity on the connection, then ensure that the allowFailOverToBasicAuth attribute of the webAppSecurity element is set to false.
  For more information about configuring a z/OS Connect Server to use TLS, see API provider confidentiality and integrity for zosConnect-2.0. For more information about using client-certificate authentication, see API provider authentication and identification.
Note: When you create an IMS service in IMS Explorer, the allowFailOverToBasicAuth attribute must be set to true.

Procedure

Configure the API toolkit with the client certificate.

Open the Preferences window by clicking Window > Preferences on the main menu.
Expand Explorer and click Certificate management.
In the keystore details section, next to the File name field, enter the full path and name of the file where the certificates are saved. You can also click Browse to navigate to the client key, select the client key, and click Open.
In the Phass phrase field, enter the password for this keystore.
In the Store type field, select the correct store type.
If you are using a smart card, select Use Windows cryptography services for the Windows operating system, which uses the standard Windows cryptography mechanism. To use a PKCS11 driver (mandatory on Mac OS and Linux® operating systems), select Use PKCS11 driver and specify the driver path and PIN.
If you are instructed by your network administrator, select the correct protocol for your organization in the Secure socket protocol field.
Click Apply and OK to save your settings and close the window.
Add a credential for the client certificate for host connections.
1. Click Window > Manage Connections to open the Host Connections view.
2. Click Add in the Credentials section and select Certificate from Keystore.
3. Specify the user ID that is associated with the certificate.
4. Choose the appropriate certificate from the list and click OK.
Select your IBM z/OS Connect Enterprise Edition connection in the Connections section and select Set Credentials.
Select the credential that you defined, and click Connect.

Results

The client certificate is used for server connection authentication. This client certificate allows the server to use the user ID that is specified for the host connection for authorization based on the defined security role.