Update certificates

The guide describes the procedure of updating TLS certificates (server.crt, server.key, and ca.crt) on the already installed WorkFusion platform environment.

Example use cases:

• The WorkFusion platform is installed initially with self-signed TLS certificates, and you want to apply certificates issued by your trusted SSL provider, for example, GoDaddy, Digicert, and so on.
• Certificates used during the initial installation expired, and you want to update them.

Prerequisites

• You have the WorkFusion platform v10.1.0 or higher installed.
• You have the SSH access to Linux servers of the environment: Master, Agent.
• You have RDP access to the RPA Windows server of the environment.
• You have no running Business Processes in the environment.
• You prepared new server.crt, server.key, and ca.crt files.

Update certificates

Standard setup

To update certificates:

1. Log in to the Master server via SSH as WFUSER, and go to the directory where installer was extracted (PACKAGE_DIR):

   $ export PACKAGE_DIR=/opt/workfusion/wf_installer
   $ cd $PACKAGE_DIR

2. Back up the current certificates:

   $ mkdir certificates_backup
   $ cp certificates/{server.crt,server.key,ca.crt} certificates_backup/

3. Place your new server.crt, server.key, and ca.crt into the certificates directory. The certificates directory content must look as follows:

   $ ls -la certificates/
   total 24
   drwxr-xr-x.  3 ec2-user ec2-user   78 Oct 27 22:50 .
   drwxr-xr-x. 12 ec2-user ec2-user 4096 Oct 27 22:50 ..
   drwxrwxr-x.  2 ec2-user ec2-user 4096 Oct 27 22:50 _auth_internal
   -rw-r--r--.  1 ec2-user ec2-user 2984 Oct 27 22:46 ca.crt
   -rw-r--r--.  1 ec2-user ec2-user 4835 Oct 27 22:46 server.crt
   -rw-r--r--.  1 ec2-user ec2-user 1674 Oct 27 22:46 server.key

   Note: do not replace or remove files inside the _auth_internal directory. The directory contains client certificates for services intercommunication. The certificates are generated automatically before the initial installation and must not be changed.

4. Prepare the environment variables:

   $ export ANSIBLE_PRIVATE_KEY_FILE="</path_to_ssh_key>"   # Path to SSH key for connection to all Linux servers as WFUSER
   $ export ANSIBLE_REMOTE_USER="WFUSER" # WFUSER provided in config.yml
   $ export ANSIBLE_VAULT_PASS="<ansible_vault_password>"   # Password for decryption of config.yml. If you don't set this variable, you'll be prompted for password

5. Stop all services:

   $ ./install.sh stop_services full

6. Update certificates:

   $ ./install.sh update_certs full

7. Start all services:

   $ ./install.sh start_services full

8. Wait for about ten minutes for environment stabilization after services startup and check that the environment is operational:

   $ ./install.sh check full -e test_ml=true -e test_ocr=true -e test_rpa=true -e test_ie=true -e test_desktop=true
   
   # If you don't have OCR in the environment - don't use "-e test_ocr=true"
   # If you don't have RPA in the environment - don't use "-e test_rpa=true -e test_ie=true -e test_desktop=true"

Multipoint setup

To update certificates:

1. Log in to each Linux server via SSH as WFUSER and go to the directory where installer was extracted (PACKAGE_DIR):

   $ export PACKAGE_DIR=/opt/workfusion/wf_installer
   $ cd $PACKAGE_DIR

2. Back up the current certificates:

   $ mkdir certificates_backup
   $ cp certificates/{server.crt,server.key,ca.crt} certificates_backup/

3. Place your new server.crt, server.key, and ca.crt into the certificates directory. The certificates directory content must look as follows:

   $ ls -la certificates/
   total 24
   drwxr-xr-x.  3 ec2-user ec2-user   78 Oct 27 22:50 .
   drwxr-xr-x. 12 ec2-user ec2-user 4096 Oct 27 22:50 ..
   drwxrwxr-x.  2 ec2-user ec2-user 4096 Oct 27 22:50 _auth_internal
   -rw-r--r--.  1 ec2-user ec2-user 2984 Oct 27 22:46 ca.crt
   -rw-r--r--.  1 ec2-user ec2-user 4835 Oct 27 22:46 server.crt
   -rw-r--r--.  1 ec2-user ec2-user 1674 Oct 27 22:46 server.key

   Note: do not replace or remove files inside the _auth_internal directory. The directory contains client certificates for services intercommunication. The certificates are generated automatically before the initial installation and must not be changed.

4. Stop all services on Linux servers. Execute the following command on each Linux server:

   $ wfmanager stop all

5. Stop services on the BI server (if the BI server exists in the environment). Connect to the BI server via RDP, open Windows CMD as Administrator, and execute:

   tsm stop

6. Stop services on the RPA server (if the RPA server exists in the environment). Connect to the RPA server via RDP, open Windows CMD as Administrator, and execute:

   net stop WFSvc

7. Update certificates on Master server(s):

   $ ./install.sh update_certs master -c local --limit <current_host>

8. Update certificates on Agent server(s):

   $ ./install.sh update_certs agent -c local --limit <current_host>

9. Update certificates on the RPA server(s):

   1. If ca.crt contains multiple certificates, extract the actual CA certificate (skip the intermediate) and save its contents in the root.crt file.

   2. Copy certificates and keys to their corresponding locations on the RPA server, as described in the following table:

      • server.crt > rpa_install_dir/nginx/ssl/server.crt
      • server.key > rpa_install_dir/nginx/ssl/server.key
      • ca.crt > rpa_install_dir/nginx/ssl/ca.crt
      • ca.crt > rpa_install_dir/filebeat/ssl/ca.crt
      • ca.crt > rpa_install_dir/metricbeat/ssl/ca.crt
      • root.crt > rpa_install_dir/nginx/ssl/root.crt

   3. Remove the existing CA certificate with a local CA alias from the Java truststore. Connect to the RPA server via RDP, open Windows CMD as Administrator, and execute:

      rpa_install_dir\java\bin\keytool.exe -delete -noprompt -alias localCA -keystore **rpa_install_dir**\java\jre\lib\\security\cacerts -storepass changeit

   4. Import a new CA certificate with a local CA alias into the Java truststore. Connect to the RPA server via RDP, open Windows CMD as Administrator, and execute:

      rpa_install_dir\java\bin\keytool.exe -import -noprompt -alias localCA -file rpa_install_dir\nginx\ssl\root.crt 
          -keystore rpa_install_dir\java\jre\lib\security\cacerts -storepass changeit

   5. Import the CA certificate into the Windows Trusted Root CA certificates store (the LocalMachine storage). Connect to the RPA server via RDP, open Explorer and double-click the rpa_install_dir/nginx/ssl/root.crt file. Click Install certificate and select Local Machine as a destination. Then, manually choose the certificate store and select Trusted Root Certificate Authorities.

   6. Remove the unneeded rpa_install_dir/nginx/ssl/root.crt file on the RPA server.

10. Start all services on Linux servers. Execute the following command on each Linux server:

    wfmanager start all

11. Start services on the RPA server (if the RPA server exists in the environment). Connect to the RPA server via RDP, open Windows CMD as Administrator, and execute:

    net start WFSvc

12. Wait for about ten minutes for environment stabilization after services startup and check that the environment is operational:

    $ ./install.sh check full -e test_ml=true -e test_ocr=true -e test_rpa=true -e test_ie=true -e test_desktop=true
    
    # If you don't have OCR in the environment, don't use "-e test_ocr=false"
    # If you don't have RPA in the environment, don't use "-e test_rpa=false -e test_ie=false -e test_desktop=false"