Installing and trusting a server certificate for Swagger UI

To use Swagger UI, because it runs on a workstation rather than the server where the API is hosted, cross-origin resource sharing (CORS) must be enabled on the server. API Explorer is hosted on the IBM® z/OS® Connect server, eliminating potential CORS issues. Because of this, API Explorer is the recommended UI for examining and invoking APIs. Both API Explorer and Swagger UI require the user to accept the self-signed certificate.

Before you begin

For more information about enabling CORS on the IBM z/OS Connect server, see Configuring Cross-Origin Resource Sharing on a z/OS Connect (OpenAPI 2) Server.

About this task

Swagger UI does not provide diagnostics when the Try It Out! function fails due to a CORS issue. CORS is enforced by the browser and Swagger UI does not have the visibility to the interaction between the browser and the resource (server).

When you use API Explorer or Swagger UI in the API toolkit to invoke an API over a secure connection, if the API is hosted on a server with a self-signed or invalid certificate, you would encounter one of the following issues:

The browser prompts you whether to accept or decline the self-signed or invalid certificate. If you accept, the request is sent to the server. If you decline, the request is not sent and Swagger UI indicates that no response is received. You are prompted again after restarting the browser.
The browser does not prompt you at all, the request is not sent to the server, and Swagger UI indicates that no response is received.

By default, when you open API Explorer or Swagger UI from within the API toolkit, the Eclipse internal web browser is used. Installing the certificate into your external web browsers might not suffice. Installing and trusting the certificate at the operating system level is the best way to ensure successful API invocation over a secure connection.

Procedure

To install and trust a IBM z/OS Connect certificate, export the server certificate from the server and import it to the workstation where the API toolkit is running.

On the IBM z/OS Connect server, export the server certificate.
- If the IBM z/OS Connect server's certificate is signed by a Certificate Authority (CA) certificate, export the CA certificate. For example,
```
RACDCERT CERTAUTH EXPORT(LABEL('ZC-CA-Cert')) DSN('ZCONN.CERT.CACERT') FORMAT(CERTDER)
        PASSWORD('password')
```
  where 'ZC-CA-Cert' is the label of the CA certificate and 'ZCONN.CERT.CACERT' is the z/OS sequential file where it will be exported to.
  Transfer the z/OS sequential file to a UNIX System Services file. For example,
```
OPUT 'ZCONN.CERT.CACERT' '/u/devuser1/zcee/server.cer' BINARY CONVERT(NO)
```
- If the IBM z/OS Connect server's certificate is a self-signed certificate, export the public part of the certificate. For example:
```
RACDCERT ID(ZOSCONN) EXPORT(LABEL('ZC-Server-Cert')) DSN('ZCONN.CERT.SRVCERT') FORMAT(CERTDER) PASSWORD('password')
```
  where 'ZC-Server-Cert' is the label of the self-signed certificate and 'ZCONN.CERT.SRVCERT' is the z/OS sequential file where it will be exported to.
  Transfer the z/OS sequential file to a UNIX System Services file. For example:
```
OPUT 'ZCONN.CERT.SRVCERT' '/u/devuser1/zcee/server.cer' BINARY
    CONVERT(NO)
```
- If the IBM z/OS Connect server is using a keystore:
  1. Locate the keystore for your IBM z/OS Connect server. The default location of the keystore is /var/zosconnect/servers/serverName/resources/security/keys.p12
  2. Extract your server certificate from its keystore. Use the Java keytool to extract the certificate into a file. In the following example, the file is named server.cer.
```
keytool -export -alias default -file server.cer 
-keystore keys.p12 -storepass zosConnect -storetype p12
```
    The message "Certificate stored in file server.cer" is displayed.
Use FTP to transfer the server.cer certificate that you exported in step 1 to your workstation.
On your workstation, complete the certification configuration steps for your operating system to import the server.cer certificate you transferred in step 2 into your workstation's trusted certificate store or key chain..
- For Windows, take the following steps to configure the certificates.
  1. Open a command prompt or PowerShell, type certmgr.msc, and press Enter.
  2. Right-click Trusted Root Certification Authorities and select All Tasks > Import.
  3. Click Next when the Certificate Import Wizard appears.
  4. On the "File to Import" page, click Browse to select and open the certificate file created in step 1.
  5. Click Next to advance to the Certificate Store page.
  6. Verify that Place all certificates in the following store and Trust Root Certification Authorities are both selected, and click Next.
  7. Examine the details of the import. If all is correct, click Finish.
  8. When prompted if you want to continue given that the certificate cannot be verified (because it is self-signed), click Yes.
  9. Restart the API toolkit and any web browsers that might be running.
- For MacOS, take the following steps to configure the certificates.
  1. Open the Keychain Access application.
  2. Select System in the Keychains view.
  3. Select Certificates in the Category view.
  4. Select File > Import items.
  5. Specify the certificate file (created in Step 1). You might be prompted for your user name and password to allow modification of the system keychain.
    The certificate is now displayed in the list, with the CN value of the certificate as its name (for example, testserver.example.org).
  6. Double-click the certificate to update its settings.
  7. In the Trust section of the displayed dialog, for the When using this certificate field, select Always Trust and close the dialog. You might be prompted for your user name and password to allow modification of the certificate settings.
  8. Restart the API toolkit and any web browsers that might be running.