Securing Connections to the AE (TLS/SSL)

The communication between the Automation Engine and the different components uses TLS/SSL through a secure WebSocket (WSS). These components establish a connection with the Java communication process (JCP) and/or the REST process (REST), which use trusted certificates to prove their identity to other communication partners, such as Agents.

Important! Check Broadcom Software Academy. There is a course available for this topic. For more information, see the Education section at the end of this topic.

This page includes the following:

Overview

The JCP and REST processes use trusted certificates to prove their identity to other communication partners, such as AWI, and the Java, Windows, and UNIX Agents.

The Automic Automation TLS/SSL implementation uses public key certificates in X.509 format and TLS version 1.2 for the secure connections between the server (Automation Engine) and the hosts (AWI, Agents, and so on).

The Java default cipher suite of the JCP is used to configure the TLS/SSL connection. You can change the supported cipher suites in the Java security policy. For more information, see https://www.java.com/en/configure_crypto.html.

Make sure you are familiar with the TLS/SSL and certificate implementation before you install and/or upgrade a TLS/SSL component. For more information, see TLS/SSL Considerations for Automic Automation.

For additional information about the different certificate types and examples of how they could be created and used, see What Kind of Certificates Should I Use for Automic Automation v21.

Important! Please note that these are only examples, not a requirement for Automic Automation and they are not meant to replace the product documentation.

Parameters - Automation Engine

For an on-premises installation, define the parameters listed below in the [TLS] section of the configuration (UCSRV.INI) file of the Automation Engine. For more information, see Automation Engine INI file.

  • keystore= Path and file where the keystore for the TLS/SSL certificate is stored

    Default value: ./httpsKeyfile

    This parameter is mandatory and must point to the correct target; otherwise, the process server will terminate.

  • keystorePassword= Password for the keystore file

    Default value: changeit

    If the value is not defined or is left empty, the system uses the default value.

  • keyPassword=Password for the key

    Default value: changeit

    If the value is not defined or is left empty, the system uses the default value.

  • keyAlias= Alias used for the key

    Default value: jetty

    If the value is not defined or is left empty, the system uses the default value.

The keystorePassword and the keyPassword can be obfuscated with the UCYBCRYP Utility. For more information, see Obfuscating Passwords.

In the Automic Automation Kubernetes Edition, the JCP by default uses a generated, self-signed certificate within the Kubernetes cluster. Therefore, you do not have to define these parameters for an AAKE installation.

If you use certificates via mutual TLS/SSL in an on-premises installation, define the following parameters in the [TLS] section of the AE INI file:

  • mutualAuthenticationKeystore= Path and file where the keystore for TLS/SSL mutual authentication is stored

    Default value: ./mutualTlsKeystore.p12

    If this parameter is not set, the system uses the definition of the keystore parameter.

  • mutualAuthenticationKeystorePassword= Password for the keystore file

    Default value: changeit

    If this parameter is not set, the system uses the definition of the keystorePassword parameter.

  • mutualAuthenticationKeyPassword= Password for the key

    Default value: changeit

    If this parameter is not set, the system uses the definition of the keyPassword parameter.

  • mutualAuthenticationKeyAlias= Alias used for the key for mutual authentication

    If this value is not defined or is left empty, the system does not attempt mutual authentication.

In the Automic Automation Kubernetes Edition, you must create the mutual-tls-cert Kubernetes secret before the installation.

Parameters - Agents, Java Components, Proxy and TLS Gateway

All Java components as well as the Proxy, the Windows, UNIX and Java Agents and the TLS Gateway can use different parameters in their corresponding INI file to define how to handle the certificates.

Important! TLS/SSL Agents (in containers and on-premises) as well as the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer, which requires a certificate for authentication.

Make sure that address of the load balancer is defined on both sides: the Automation Engine and the Agent / TLS Gateway and that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to AWI, the JCP and REST Processes Using an Ingress.

For more information, see Connecting to AWI, the JCP and REST Processes Using an Ingress.

This applies to the following components and Agents:

Components

Agents

Note: The TLS/SSL implementation does not apply to the HP-UX Agent, as it is no longer supported in this version.

When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default; that is the Java trust store for Java components and Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. In this case, you only have to check that the root certificates already are in the respective store.

If the relevant certificates are not there and you want to import them, you can use OS or Java specific tools for that purpose, such as Keytool, cert-manager, OpenSSL and such. For more information on how to use those tools, please refer to the respective product documentation.

If you do not want to use the default locations for the components and Agents listed above, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

Furthermore, the Agents can use the following parameters in the [AUTHORIZATION] section of the respective INI file:

  • agentSecurityFolder= Path to the folder where the agent stores security related files such as private keys, signed certificates, root certificates

  • keyPassword= Password for the key

    Default value: changeit

    If the value is not defined or is left empty, the system uses the default value.

    Note: The keyPassword can be obfuscated with the UCYBCRYP Utility. For more information, see Obfuscating Passwords.

The Agent searches for certificates in the most common TLS/SSL stores. If you do not use a default location, the UNIX agents additionally require you to define the SSLCertDir= and SSLCertFile= parameters to load the certificates from the TLS/SSL store.

Default SSLCertDir

  • /etc/ssl/certs

    Platforms: Debian/Ubuntu

  • /etc/pki/tls/certs

    Platforms: Fedora/RHEL/CentOS

  • /usr/local/share/certs

    Platforms: FreeBSD

  • /etc/openssl/certs

    Platforms: NetBSD

  • /var/ssl/certs

    Platforms: AIX

Default SSLCertFile

  • /etc/ssl/certs/ca-certificates.crt

    Platforms: Debian/Ubuntu

  • /etc/pki/tls/certs/ca-bundle.crt

    Platforms: Fedora/RHEL 6/CentOS

  • /etc/ssl/ca-bundle.pem

    Platforms: OpenSUSE

  • /etc/pki/tls/cacert.pem

    Platforms: OpenELEC

  • /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem

    Platforms: CentOS/RHEL 7

  • /etc/ssl/cert.pem

    Platforms: Alpine Linux

If the Agent does not find any certificates or the paths do not exist in your system, then the Agent is not able to connect to the Automation Engine.

You can use different commands to search for the certificates in your system. Only a privileged user, such as root, can search in these folders.

Examples - SSL_CERT_DIR

sudo find /etc/ssl/ -name '*DigiCert*'

sudo find /etc/ -name 'DigiCert_Global_Root_CA.pem'

Examples - SSL_CERT_FILE

sudo grep -R "DigiCert" /etc/ssl/

sudo grep -R "DigiCert Global Root CA" /etc/

More information:

Certificate Expiration Date

You have to make sure that the certificates being used not only meet the respective security requirements, but also are not expired. Otherwise, the components cannot connect to the Automation Engine.

The system checks the certificate expiration date every 24 hours (at midnight UTC). When one or more certificates is close to expiring, that is, if the expiration date is within 30 days, AWI displays the following notification: "The following JCP certificates will expire within the next 30 days: <certificate name (expiration date)>". The expiration date of the certificate is also written into the JCP log file on startup as well as at midnight (UTC).

The notification is displayed in all Clients but only to users with the privilege Access to Administration, see Granting Automation Engine Privileges .The notification remains visible until the certificate is renewed.

Notes:

  • AWI displays only one notification even if there is more than one certificate about to expire. All relevant certificates are listed one after the other separated by a comma sorted by expiration date; the certificate closest to the expiration date is listed first.

  • It is not necessary to restart the JCP after renewing the certificate.

  • Make sure that the new certificate is set correctly and uses the same definition as the TLS section of the INI file of the Automation Engine, see Automation Engine. Otherwise, the old KeyStore definition is used and the JCP will not start.

Optionally, you can also use the UC_SERVER_TLS_SETTINGS variable to trigger a custom action if one of these certificates is close to expiring. For more information, see UC_SERVER_TLS_SETTINGS - Server Certificate Management.

Education

The Broadcom Software Academy provides a wide range of free online trainings. For information about how to navigate through the Academy and on how to register for courses, see Free Online Courses.

The following course(s) are associated with this topic:

See also: