🚧

Important!

The installation process generates self-signed certificates on your behalf. These certificates will expire in 90 days, and you must replace them with certificates signed by a trusted Certificate Authority (CA) as soon as installation completes. If you do not update the certificates, the installation will stop working in 90 days.

The installation bundle provides a cluster management tool that enables you to update certificates post-installation. To access the tool, navigate to the location of the installer bundle:

cd /opt/UiPathAutomationSuite/

Generating a Certificate Signing Request (CSR) and a private key

To generate the CSR and the private key, run the following command:

# copy the machine openssl configuration locally
cp /etc/pki/tls/openssl.cnf ./openssl.tmp.cnf

# Replace the [AUTOMATION_SUITE_FQDN] value. For example, "automationsuite.corp.com"
AS_FQDN=[AUTOMATION_SUITE_FQDN]
cat >> ./openssl.tmp.cnf <<EOF
[SAN]
subjectAltName=DNS:$AS_FQDN,DNS:alm.$AS_FQDN,DNS:monitoring.$AS_FQDN,DNS:registry.$AS_FQDN,DNS:objectstore.$AS_FQDN,DNS:insights.$AS_FQDN
EOF

# create the certificate request
openssl req -new -sha256 -newkey rsa:2048 -nodes -keyout server.key -subj "/C=xx/ST=xx/O=xx/OU=xx/CN=$AS_FQDN" -reqexts SAN -config openssl.tmp.cnf -out ${AS_FQDN}.csr

Your IT team uses the obtained values to generate a signed certificate. The generated private key remains local.

Managing server certificates

Run the following command to view more information about server certificates.

sudo ./configureUiPathAS.sh tls-cert --help

Output

************************************************************************************

Manage cluster tls and server certificate

Usage:
  configureUiPathAS.sh tls-cert [command]
  configureUiPathAS.sh tls-cert [flags]

Available Commands:
  update                              Update the tls / server certificate

  get                                 Get the tls / server certificate

Flags:
  -h|--help                           Display help

************************************************************************************

Below are the operation you can perform using the ./configureUiPathAS.sh tls-cert command.

Updating the server certificate

Online installation: How to find the server certificate

Certificates are stored as a secret at the Istio level. You can find certificates under the istio-ingressgateway-certs name in the istio-system namespace.
See the certificate files in the following list:

• Server TLS certificate is stored as tls.crt
• Server TLS private key as tls.key
• CA bundle is stored as ca.crt

You can verify the secrets using the following command :

kubectl -n istio-system get secrets istio-ingressgateway-certs -o yaml

Certificates are also stored in the UiPath namespace. This is applicable to every UiPath product that needs certificate information to trust incoming calls. For details, see Understanding the container architecture related to certificates.

Offline installation: How to find the server certificate

In addition to the certificates required by online deployment, an offline deployment has two additional locations that use the same rootCA.crt and tls.crt: ArgoCD and Docker Registry. Certificates are then stored in both Docker and ArgoCD namespaces.

You can verify the secrets using the following command :

# For docker registry
kubectl -n docker-registry get secrets docker-registry-tls -o yaml
# For Argocd
argocd cert list --cert-type https

How to update server certificates

🚧

Important!

You must decrypt the certificate key before updating the server certificate. Skipping the decryption step would result in an error.

To decrypt the certificate key, run the following command:

# replace /path/to/encrypted/cert/key to absolute file path of key
# replace /path/to/decrypt/cert/key to store decrypt key
# Once prompted, please entry the passphrase or password to decrypt the key

openssl rsa -in /path/to/encrypted/cert/key -out /path/to/decrypt/cert/key

Run the configureUiPathAS.sh script to update the certificate as shown below. You need the path to each of the three certificate files. All the certificate file should be in PEM format.

• Certificate Authority Bundle - This bundle should contain only the chain certificates used to sign the TLS server certificate. The chain limit is up to nine certificates.
• Server Certificate - Public server certificate
• Private key - Private key for server certificate

sudo ./configureUiPathAS.sh tls-cert update --ca-cert-file /path/to/cacert --tls-cert-file /path/to/tlscert --tls-key-file /path/to/tlskey

Below files will be stored in in the /directory/path/to/store/certificate location.

Accessing the TLS certificate

To print out the certificate files, run the following command, specifying the directory where certificates are stored.

sudo ./configureUiPathAS.sh tls-cert get --outpath /directory/path/to/store/certificate

Adding the CA certificate to the host trust store

Making sure the generated certificates are trusted is your responsibility.
To add the certificate to the host VM trust store, run the following commands:

# 1. Copy the certificate file to the /usr/share/pki/ca-trust-source/anchors/ or the /etc/pki/ca-trust/source/anchors/ directory
cp /path/to/the/ca-cert /usr/share/pki/ca-trust-source/anchors/

# 2. Update the trust store configuration
update-ca-trust

Managing additional CA certificates

Run the following command to view more information about additional CA certificates.

./configureUiPathAS.sh additional-ca-certs --help

Output

***************************************************************************************

Manage additional CA certificates, this can be used to add sql server CA

Usage:
  configureUiPathAS.sh additional-ca-certs [command]
  configureUiPathAS.sh additional-ca-certs [flags]

Available Commands:
  update                              Update the additional trusted CA certificates.

  get                                 Get the additional trusted CA certificates

Flags:
  -h|--help                           Display help

***************************************************************************************

Below are the operation you can perform using the ./configureUiPathAS.sh additional-ca-certs command.

Updating the CA certificates

This command helps you update or replace the existing configured CA certificates.

./configureUiPathAS.sh additional-ca-certs update --ca-cert-file /path/to/ca/certs

📘

Note:

The command above adds a new certificate to the list of existing certificates. if you want to replace all the previously configured certificates, make sure to append --replace at the end.

The CA Certificate bundle file should be a valid .pem format and can have more than one certificate present in it.

Accessing the CA certificates

Run the following command to download the already configured CA certificates.

./configureUiPathAS.sh additional-ca-certs get --outpath /path/to/download/certs

Adding the CA certificate to the host trust store

Making sure the generated certificates are trusted is your responsibility.
To add the certificate to the host VM trust store, run the following commands:

# 1. Copy the certificate file to the /usr/share/pki/ca-trust-source/anchors/ or the /etc/pki/ca-trust/source/anchors/ directory
cp /path/to/the/ca-cert /usr/share/pki/ca-trust-source/anchors/

# 2. Update the trust store configuration
update-ca-trust

Managing identity token signing certificate

Run the following command to view more information about identity token signing certificates.

sudo ./configureUiPathAS.sh identity token-cert --help

Output

************************************************************************************

Manage Identity token signing certificate

Usage:
  configureUiPathAS.sh identity token-cert [command]
  configureUiPathAS.sh identity token-cert [flags]

Available Commands:
  update                              Update secondary certificate to signing
                                        the authentication token
  rotate                              Switch secondary certificate as a primary
                                        token signing certificate
  get                                 Get token signing certificate

Flags:
  -h|--help                           Display help

************************************************************************************

Below are the operation you can perform using ./configureUiPathAS.sh identity token-cert command

For the token signing certificate, you need to rotate using two steps.

Updating the certificate

To upload the new certificate to sign the token, run the following command:

📘

The following command does not replace the existing token signing certificate.
Make sure the certificate you provide is in .pem format.

sudo ./configureUiPathAS.sh identity token-cert update --cert-file-path /path/to/cert --cert-key-file-path /path/to/certkey

Rotating the certificate

To rotate or replace the old certificate with the new one, run the following command:

sudo ./configureUiPathAS.sh identity token-cert rotate

📘

Note:

There should be the lead time of about 24 - 48 hours between certificate update and rotate.
We need this lead time to keep supporting the authentication for cached token signed by old certificate.
If you rotate the certificate too soon before the expiry of cache token can result in downtime. And you may have to restart all your robots.

Emergency certificate rotation

🚧

Important!

The following procedure is for emergencies only. You should rotate certificates ahead of their expiration dates

To perform an emergency certificate update, take the following steps:

1. Obtain a new certificate or create a self-signed one and copy it to the cluster server node used to execute the next rotation steps.

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout identityserver.key -out identityserver.crt
openssl pkcs12 -export -out identityserver.pfx -inkey identityserver.key -in identityserver.crt

2. If IdentityServer1.pfx is expired, rotate and update the certificate. For instructions, see Rotating the certificate.

3. If IdentityServer2.pfx is expired, update the certificate.

4. If both certificates are expired, update, rotate and update again.

5. Restart all deployments. For instructions, see Troubleshooting.

6. Clear all browser caches. If you run in Incognito or Private mode, you can skip this step.
   a. For Firefox, press CTRL+SHIFT+DEL, select Cache, and click OK.
   
   b. For Chrome, press CTRL+SHIFT+DEL, select Cached images and files, and click Clear data.
   

Accessing the certificate

Run the following command to download the current token signing certificate:

sudo ./configureUiPathAS.sh identity token-cert get --outpath /directory/path/to/store/certificate

Managing Rancher certificates

By default, Rancher RKE2 certificates expire in 12 months. In the 90 days prior to their expiration date, certificates are rotated when you restart Rancher.

To manually rotate the certificates, refer to RKE2 - Advanced Options - Certificate rotation.