Adding an external server certificate to AI Optimizer for IBM Z and IBM LinuxONE

Edit online

By default, a server certificate is automatically installed during the initial configuration of the AI Optimizer for Z and LinuxONE SSC LPAR. The certificate is local, self-signed, and intended for short-term use by administrators who need immediate HTTPS access to the IBM Z Appliance Container Infrastructure (zACI) REST API. For enhanced network security in the long term, add an external server certificate that is signed by a trusted third-party certificate authority (CA).

Before you begin

Before getting started, ensure that you have the following resources and information ready:

The IP address of the AI Optimizer for Z and LinuxONE SSC LPAR. See Installing and configuring AI Optimizer for IBM Z and IBM LinuxONE for details.
Administrative access to the AI Optimizer for Z and LinuxONE SSC LPAR.
Access to the AI Optimizer for Z and LinuxONE REST API.
curl and jq command-line tools installed on your system.

Procedure

Obtain an authentication token from the zACI system API.

An authentication token is a short-lived credential that is usually valid for 30 minutes. You will use the token to generate a Certificate Signing Request (CSR).
Submit an HTTPS POST API request by running the following curl command:
```
token=$(curl -k -X POST https://<ssc-lpar-ip>:<port>/api/com.ibm.zaci.system/api-tokens \
   -H "zACI-API: com.ibm.zaci.system/1.0" \
   -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0" \
   -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" \
   -d '{
         "kind": "request",
         "parameters": {
           "user": "<username>",
           "password": "<password>"
           }
        }' | jq -r '.parameters.token')
echo $token
```
Where:
- <ssc-lpar-ip> is the IP address of your AI Optimizer for Z and LinuxONE SSC LPAR.
- <port> is the port number of your AI Optimizer for Z and LinuxONE SSC LPAR.
- <username> is your username for the Appliance Manager or the Inference router UI.
- <password> is your password for the Appliance Manager or the Inference router UI.
- The -k flag bypasses SSL certificate verification. For production environments, consider using proper SSL certificates and excluding the flag from the command.
The command will return a JWT token string as shown in the following example:
```
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhZG1pbiI6dHJ1ZSwidXNlciI6InlvZGEiLCxxxxxxx
```

Generate a Certificate Signing Request (CSR) from the SSC LPAR.

Submit an HTTPS POST API request by running the following curl command:

curl -k -X POST https://<ssc-lpar-ip>/api/com.ibm.zaci.system/certificates/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" \
  -H "ZACI-API: com.ibm.zaci.system/1.0" \
  -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0" \
  -d '{
    "kind": "request",
    "parameters": {
      "ca": false,
      "ip": "<ssc-lpar-ip>",
      "c": "<country>",
      "st": "<state>",
      "o": "<organization>",
      "ou": "<organization_unit>"
    }
  }'

Where:

<token> is the authentication token that you obtained in Step 1.
<country> is the two-letter code for the country of the certificate user, such as US.
<state> is the two-letter code for the state or province of the certificate user, such as CA.
<organization> is the name of the business organization of the certificate user, such as IBM.
<organization_unit> is the name of the organizational unit of the certificate user, such as IBMZ.

Tip: Valid values for the c, st, o, and ou fields must be between 2 and 64 characters in length and may contain only alphanumeric characters. Whitespace and special characters are not allowed.

The command returns a JSON response with the requested CSR that is similar to the following example:

{
  "kind": "instance",
  "self": "/api/com.ibm.zaci.system/certificates/v1",
  "resource-name": "certificates",
  "resource-version": "v1",
  "properties": {
    "issued-by": "C=IN, ST=TN, O=IBM, OU=IBMZ, CN=HOST-AIOPT4",
    "issued-to": "C=IN, ST=TN, O=IBM, OU=IBMZ, CN=HOST-AIOPT4",
    "state": "csr",
    "hostname": "N, ST=TN, O=IBM, OU=IBMZ, CN=HOST-AIOPT4",
    "ca": false,
    "names": [
      "N, ST=TN, O=IBM, OU=IBMZ, CN=HOST-AIOPT4",
      "HOST-AIOPT4",
      "<ssc-lpar-ip>"
    ],
    "id": "9ea11664-b5d3-4b92-8059-05507988308c",
    "csr": "-----BEGIN CERTIFICATE REQUEST-----MIICwTCCAakCAQAwTTELMAkGA1UEBhMCSU4xCzAJBgNVBAgMAlROMQ
           wwCgYDVQQKDANJQk0xDTALBgNVBAsMBElCTVoxFDASBgNVBAMMC0hPU1QtQUlPUFQ0MIIBIjANBgkqhkiG9w0BAQEF
           AAOCAQ8AMIIBCgKCAQEAvhDkUUEe4Cw5Q4z73yBQEOLEpx60sguWIrXO0U/lAkG5XOSZTKu5ORQPpnLXj8/CE7lSOZ
           Oo3DI6COURkX004R0B4KUieqhxmLzrEjcgiJjLKxd+858da7D85kf/tHPEBHjerkUEA7ymuvCfV/N0n0/4oLlLoBD5
           U82jKex61DVy2DQB+FIFWf0bw3ZwulDLvNg8UAp6ehOe3uqi0FtV8P+WBYjLBCs6kKn6KH5c3XAKYQGA63QLpR2RDb
           sbvBZOMdcv2Bm+rz2a1XQGy3/mCAwp5IxMR1QttLhSs/TZSqAg16bEH6KGytPeHMlsX7fAO6pXFITZwtoaykBFpNyl
           TwIDAQABoC8wLQYJKoZIhvcNAQkOMSAwHjAcBgNVHREEFTATggtIT1NULUFJT1BUNIcECS9WZzANBgkqhkiG9w0BAQs
           FAAOCAQEAfE0Aao6ZB+DCNdPwLBPJp+FKahrc7IDonpO1emT/eVkES3fCHX8UcJIlBQLoltnDyhW6WbwXFG3wnp48L
           XCq+8mfE4sTDfnmaI6EO3P1HOAcCJswMkZymFy4QWnn3+qScPWeLA4lZWlmPc974wyQ6xCKX+zMmf3wRLE44fajD3G
           P0AyTAMXxRFHGqsyh7IOnmt4WbUko3jg5gWlNZW82hOHxvKhgasOLIa0D0l0V9hfxR3xNV9YUCRhSNrNJ855dYJ8Qm
           LNGU62DI66ayq0xGM6phN9594o5ab53EczhuoZDSA0f7TK14PGwpje/Rik2PM6qcr/MlnoBgHkZB7SQlw==
           -----END CERTIFICATE REQUEST-----"
  }
}

Where:

9ea11664-b5d3-4b92-8059-05507988308c is the id value that you will specify when you upload the signed server certificate to the LPAR.

Get the CSR signed by a trusted third-party CA.
Concatenate the signed server certificate, intermediate certificate, and root certificate into a single PEM file.
The CSR response includes -----BEGIN CERTIFICATE REQUEST----- and -----END CERTIFICATE REQUEST-----. All certificate content must be included between these two lines. Ensure that the third-party root CA is present in the client truststore to validate the server certificate and establish a secure connection.

The combined certificate file must be in PEM format (text/plain). You can upload a .pem file only. Verify the format of the combined certificate file by running the following command:
```
% file ca.crt
ca.crt: PEM certificate
```

Upload the signed server certificate to the SSC LPAR.

Submit an HTTPS PUT API request by running the following curl command:

curl -k -X PUT "https://<ssc-lpar-ip>/api/com.ibm.zaci.system/certificates/v1/9ea11664-b5d3-4b92-8059-05507988308c" \
-H "Content-Type: text/plain; charset=utf-8" \
-H "Authorization: Bearer <token>" -H "ZACI-API: com.ibm.zaci.system/1.0" \
-H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0" \
--data-binary "@signed-server-cert.pem" | jq

9ea11664-b5d3-4b92-8059-05507988308c is the id value that you include as part of the URI for the request.
<token> is the authentication token that you obtained in Step 1. Remember that an authentication token usually expires after 30 minutes. If needed, run Step 1 again to obtain a new token.
@signed-server-cert.pem is the name of the single server certificate file in PEM format that is already signed by a trusted third-party CA.

The command returns a JSON response that is similar to the following example:

{
  "kind": "instance",
  "self": "/api/com.ibm.zaci.system/certificates/v1/9ea11664-b5d3-4b92-8059-05507988308c",
  "resource-name": "certificates",
  "resource-version": "v1",
  "properties": {
    "serial": "02FD57",
    "fingerprint": "E1:72:29:xx:49:xx:97:64:F3:8F:xx:4C:B8:1B:xx:09:9D:xx:58:FF",
    "issued-to": "C=IN, ST=KA, L=IBMBlr, O=ibm.com, OU=ibm.com, CN=HOST-B02SSC2, UID=005O9P744, mail=emailid@ibm.com",
    "issued-by": "C=US, O=International Business Machines Corporation, CN=IBM INTERNAL INTERMEDIATE CA",
    "not-before": 1762837200,
    "crt": "-----BEGIN CERTIFICATE-----
    +igAwIBAgIDAv1XMA0GCSqGSIb3DQEBCwUAMGoxCzAJBgNVBAYTAlVTMTQwMgYDVQQKEytJbnRlcm5hd
     hpbmVzIENvcnBvcmF0aW9uMSUwIwYDVQQDExxJQk0gSU5URVJOQUwgSU5URVJNRURJQVRFIENBMB4XD
     ExMTA0NTk1OVowgaYxCzAJBgNVBAYTAklOMQswCQYDVQQIEwJLQTEPMA0GA1UEBxMGSUJNQmxyMRAwD
     -----END CERTIFICATE-----",
    "not-after": 1825909199,
    "names": [
      "N, ST=KA, L=IBMBlr, O=ibm.com, OU=ibm.com, CN=HOST-B02SSC2, UID=005O9P744, mail=email@ibm.com",
      "HOST-B02SSC2",
      "$SSC_IP"
    ],
    "state": "crt",
    "hostname": "N, ST=KA, L=IBMBlr, O=ibm.com, OU=ibm.com, CN=HOST-B02SSC2, UID=005O9P744, mail=email@ibm.com",
    "ca": false,
    "id": "9ea11664-b5d3-4b92-8059-05507988308c",
    "csr": "-----BEGIN CERTIFICATEREQUEST-----
    MIICyjCCAbICAQAwVTELMAkGA1UEBhMCSU4xCzAJBgNVBAgMAktBMRAwDgYDVQQKDAdpYm0uY29tMRAwDgYD
    wYDVQQDDAxIT1NULUIwMlNTQzIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDDDzP9nY57VshYWE
    uVzCEbvGbEXtA1teC5/BGKckZ0JvZeeHEl7+jUJktqI1af7oEDMFFqsKSEGGY2lIw2MFZZvgUN2v9dRAA6HJ
    9u7hE4IVViX+5V+VCfxtuSJ19Xh13K/lh13dD8oFOjUas+jfc+vHInHO4K17IswvR7FAU5I7QNbGhKwMeN3+
    -----END CERTIFICATE REQUEST-----"
  }

Activate the CA-signed server certificate that you just uploaded.

Submit an HTTPS POST API request by running the following curl command:

curl -k -X POST "https://<ssc-lpar-ip>/api/com.ibm.zaci.system/certificates/v1/9ea11664-b5d3-4b92-8059-05507988308c?action=activate" \
-H "Authorization: Bearer <token>" \
-H "ZACI-API: com.ibm.zaci.system/1.0" \
-H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Where:

<token> is the authentication token that you obtained in Step 1. If needed, run Step 1 again to obtain a new token.