Trusting certificates off platform

Zowe services are protected by the certificates you set in your zowe.yaml configuration file, and these certificates are presented to all clients connecting to Zowe, including off-platform clients. If you are using your browser to view Zowe's API Mediation Layer or Web Desktop, or if you are using Zowe Explorer with an API Mediation Layer connection profile, the certificate Zowe presents may be challenged by your browser or operating system. This article covers a common method for trusting certificates: importing them in your off-platform client environment.

Importing a certificate Authority (CA)

Importing a certificate authority (CA) is a prerequisite to importing a PKCS12 certificate. Use the method that applies to your use case.

• Manually importing a certificate authority into a web browser
• Importing commands according to your operating system

Manually importing a certificate authority into a web browser

To avoid the browser untrusted CA challenge, import Zowe certificates into the browser.

Trust in the API ML server is a necessary precondition for secure communication between the browser or API Client application. Ensure this trust by installing a Certificate Authority (CA) public certificate. By default, API ML creates a local CA. Import the CA public certificate to the truststore for REST API clients and to your browser. You can also import the certificate to your root certificate store.

tip

If a SAF keyring is used and the certificate was generated on z/OS, the procedure to obtain the certificate does not apply. In this case, we recommended that you work with your security system administrator to obtain the certificate.

The public certificate in PEM format is stored in a USS directory a defined in the zowe.yaml configuration file in the section zowe.certificate.pem.certificateAuthorities. The certificate is stored in UTF-8 encoding so you need to transfer the certificate as a binary file. Since this is the certificate to be trusted by your browser, it is recommended to use a secure connection for transfer.

note

Windows currently does not recognize the PEM format. For Windows, use the P12 version of the local_cer.

Importing commands according to your operating system

To import the certificate to your root certificate store and trust it, follow the applicable procedure based on your operating system.

For Windows, click here for command details.

certutil -enterprise -f -v -AddStore Root localca.cer

Note: Ensure that you open the terminal as administrator. This operation installs the certificate to the Trusted Root Certification Authorities.

For macOS, click here for command details.

$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain localca.cer

For Firefox, click here for command deails.

Manually import your root certificate via the Firefox settings, or force Firefox to use the Windows truststore. As a default, Firefox uses its own certificate truststore.

Create a new Javascript file firefox-windows-truststore.js at C:\Program Files (x86)\Mozilla Firefox\defaults\pref with the following content:

/* Enable experimental Windows truststore support */
pref("security.enterprise_roots.enabled", true);

tip

To avoid requiring each browser to trust the CA that signed the Zowe certificate, you can use a public certificate authority to create a certificate. Optional public certificate authorities include Symantec, Comodo, Let's Encrypt, or GoDaddy. Certificates generated by such public CAs are trusted by all browsers and most REST API clients. This option, however, requires a manual process to request a certificate and may incur a cost payable to the publicly trusted CA.

Importing a local CA certificate on Linux

Zowe also supports importing certificates to make REST HTTPS curl request from the command line.

Follow these steps to import local_ca.cer from the path .../zowe/keystore/local_ca.

note

Steps are verified with Ubuntu 20.04.6 LTS.

1. Rename local_ca.cer with local_ca.crt and copy to the shared ca-certificates path.

   $ cp local_ca.cer /usr/local/share/ca-certificates/zowe_local_ca.crt

2. Execute a ca-certificate store update by running the following command:

   $ sudo update-ca-certificates

3. Verify that the new expected certificate was added (the newest will be at the bottom of the list which contains an extended list of concatenated CAs).

   $ cat /etc/ssl/certs/ca-certificates.crt

4. Run a basic curl HTTPS request from the command line. For example, run the following command:

curl --request 'GET'
--url 'https://tvt6092.svl.ibm.com:7554/jobs/api/v1?owner=ibmuser&prefix=*'
--header 'Authorization: Basic ************'

Next steps

Once your certificate is successfully imported, review the documentation about how to use certificates in a Zowe production environment.