SSL Configuration for the Server Automation REST API

This topic describes how to configure SSL certificates for the Server Automation REST API on IBM WAS Liberty and on the Node.js-based service. For WAS Liberty, generate a CSR with OpenSSL, create a PKCS12, import it into a Java keystore, update server.xml as needed, and restart the service. For Node.js, replace server.cert and server.key with your certificates, restart SARESTSERVICE, and verify successful startup in the logs.

Depending on the version of the SA REST API you use, you can use the following procedures to configure an SSL certificate.

If necessary, review the OpenSSL documentation at http://www.openssl.org for information about OpenSSL commands and options.

IBM WAS Liberty Profile

If you use the IBM WebSphere Application Server (WAS) Liberty Profile version of the SA REST API, complete the following procedure to configure the SSL certificate.

Procedure
  1. Generate a Certificate Signing Request (CSR) and private key. Using OpenSSL, enter a command such as the following:

    $> openssl req -nodes -newkey rsa:4096 -keyout <hostname>.key -out <hostname>.csr -sha512 -subj '/C=<country>/ST=<state>/L=<location>/O=<organization>/OU=<unit>/CN=<hostname>/subjectAltName=DNS.1=<hostname(not fully qualified)>'
    For example, to create a request for the host 'serverA.acme.com' for an organization called ACME Inc.:
    $> openssl req -nodes -newkey rsa:4096 -keyout serverA.key -out serverA.csr -sha512 -subj '/C=US/ST=CA/L=Los Angeles/O=ACME Inc./OU=IT Dept./CN=serverA.acme.com/subjectAltName=DNS.1=serverA'

  2. Have the CSR signed by your organization's Certificate Authority (CA), or by an external CA, and a signed certificate will be returned (the actual file extension of the returned certificate might vary, for example serverA_signed.crt or serverA_signed.pem). Check the contents of the certificate using a command such as:

    $> openssl x509 -in <certificate_file> -text -noout
    For example, $> openssl x509 -in serverA_signed.crt -text -noout

  3. The PKCS12 format, which combines the certificate and private key into a single file, is required, so the artifacts need to be converted (again, using OpenSSL). The CA public certificate file should be provided to you by the CA used to sign the CSR in step 1. A new password (for example changeit) is required when prompted:

    $> openssl pkcs12 -export -in <signed_cert_file> -inkey <hostname>.key -out <hostname>.p12 -name default -CAfile <CA_cert_file>
    For example,
    $> openssl pkcs12 -export -in serverA_signed.crt -inkey serverA.key -out serverA.p12 -name default -CAfile acme_ca.crt
    $> Enter Export Password: changeit
    $> Verifying - Enter Export Password: changeit

  4. Shut down the Server Automation REST API by stopping the 'WASLiberty' Windows service.
  5. The default location for the Java keystore used by SA REST is C:\WASLiberty\wlp\usr\servers\defaultServer\resources\security\key.jks. You must overwrite it with a new Java keystore file with the PKCS12 certificate imported into it. First, if this JKS file already exists, rename it to something else.

    $> cd C:\WASLiberty\wlp\usr\servers\defaultServer\resources\security
    $> move key.jks key.jks.orig
    $> keytool -importkeystore -deststorepass <new_keystore_password> -destkeypass <new_key_password> -destkeystore key.jks -srckeystore <full_path_to_<hostname>.p12> -srcstoretype PKCS12 -srcstorepass <pass_used_in_p12_keystore> -alias default
    For example, assuming serverA.p12 is located in C:\certs\
    $> "C:\WASLiberty\wlp\service\ibm-java-jre-8011-win-i386\jre\bin\keytool.exe" -importkeystore -deststorepass changeit -destkeypass changeit -destkeystore key.jks -srckeystore C:\certs\serverA.p12 -srcstoretype PKCS12 -srcstorepass changeit -alias default

    Note: Use the keytool.exe file that comes bundled with the Server Automation REST API for this, as shown in the example. The default location is: C:\WASLiberty\wlp\service\ibm-java-jre-8011-win-i386\jre\bin\keytool.exe.
  6. Check the contents of the new keystore, as follows:

    $> keytool -list -v -keystore key.jks
    For example,
    $> "C:\WASLiberty\wlp\service\ibm-java-jre-8011-win-i386\jre\bin\keytool.exe" -list -v -keystore key.jks
    Enter keystore password: changeit
    Keystore type: jks
    Keystore provider: IBMJCE
    Your keystore contains 1 entry
    Alias name: default

  7. Update the server.xml file (located at C:\WASLiberty\wlp\usr\servers\defaultServer\server.xml by default) if necessary to point to the newly created keystore. You do not need to perform this step if the keystore created in step 5 was C:\WASLiberty\wlp\usr\servers\defaultServer\resources\security\key.jks. However, you must update the password in server.xml if you are not using changeit in the steps above.
    <!--+| SECURITY CONFIGURATIONS +-->
<sslDefault sslRef="defaultSSLSettings"/>
<keyStore id="defaultKeyStore" password="changeit"/>
<ssl id="defaultSSLSettings" keyStoreRef="defaultKeyStore" sslProtocol="TLSv1.2"/>
  8. Restart the Server Automation REST API by starting the 'WASLiberty' Windows service.
  9. If not already present, the public certificate of the CA used to sign the new server certificate must be imported (and trusted as a CA) into any client (such as a browser) connecting to the SA REST API.

Node.js-based SA REST API

If you use the Node.js-based SA REST API, during installation, self-signed certificates are created automatically inside the folder <SA REST Installation folder>/sa_rest_node/sslCert with the names server.cert and server.key.

If you want to use your custom certificates (self-signed or CA-signed certificates), complete the following procedure.

Procedure

  1. Replace your custom certificates in the folder <SA REST Installation folder>/sa_rest_node/sslCert. Ensure that the file names, including the extensions, remain exactly the same as server.cert and server.key.

  2. Restart the service SARESTSERVICE.
  3. Check whether the service starts successfully, without any errors, by viewing the logs in the folder <SA REST Installation folder>/sa_rest_node/logs.