Set secure agent connections

This topic provides an overview of SSL mutual authentication and explains how to set up mutual authentication for PulseUno servers and agents.

Overview

Secure Socket Layer (SSL) technology enables clients and servers to communicate securely by encrypting all communications.

Data is encrypted before being sent, and decrypted by the recipient so that communications cannot be deciphered or modified by third parties. In PulseUno, you can enable a server to optionally communicate with its agents using SSL in mutual authentication mode.

In mutual authentication mode, communications are encrypted, but users are required to authenticate themselves by providing digital certificates.

A digital certificate is a cryptographically signed document intended to guarantee the identity of the certificate's owner. PulseUno certificates are self-signed.

When mutual authentication mode is active, PulseUno uses it for JMS-based server communication (via SSL from PulseUno to agents) and agent communication (via HTTPS from agents to PulseUno). In this mode, the PulseUno server provides a digital certificate to each agent, and each agent provides one to the server.

You can set up mutual authentication during server/agent installation, or activate it later.

Caution: Ensure that mutual authentication mode is turned on for both server and agents. Otherwise, they cannot connect. If one party uses mutual authentication mode, they must all use it.

Back to top

Configure mutual authentication

Follow these steps to enable mutual authentication for PulseUno servers and agents.

Prerequisite: Before configuring mutual authentication and exchanging keys, set the server and agent properties.

To set up mutual authentication:

  1. Verify that your PulseUno server and agents are not running.

  2. Run this command on the server to create a new key store and a private key for the server (if they do not exist):

    Copy code 
    tomcatDir\conf> keytool -genkey -alias <your_alias> -keyalg RSA -keystore <your_keystore_file>.jks

    Example: Use this example with the host name of a PulseUno server as the CN distinguished name:

    C:\Program Files\OpenText\common\tomcat\9.0\conf> keytool -genkey -noprompt -alias pulse -keyalg RSA -keystore server-ssl.jks -keypass 123456 -storepass 123456 -dname "CN=<pulse-hostname>, OU=pulse, O=Company, L=Location, ST=PU, C=PU"

  3. To create a new Connector entry, add the following lines to the <tomcatDir>\conf\server.xml file on the server:

    Copy code 
    <Connector port="8443" scheme="https" secure="true" 
    SSLEnabled="true" clientAuth="false" 
    sslEnabledProtocols="TLSv1.2,TLSv1.1,TLSv1" sslProtocol="TLS" 
    keyAlias="pulse" keystoreFile="C:\Program Files\OpenText\common\tomcat\9.0\conf\server-ssl.jks" 
    keystorePass="123456" truststoreFile="C:\Program Files\OpenText\common\tomcat\9.0\conf\server-ssl.jks" 
    truststorePass="123456" ...
    </Connector>
    <!-- In this example keystore and truststore is the same file, but in general they could be separated -->
    <!-- if keystore has several aliases, a proper should be chosen. In this example, "pulse" -->

    Do not use the same port number that is used in an existing Connector entry.

  4. On the PulseUno server, open the startup.properties file in the <pulse_data>\conf directory:

    Default locations:

    Windows C:\ProgramData\OpenText\PulseUno\pulse_data\conf
    Linux /opt/opentext/pulseuno/data/pulse_data/conf

    Add the following properties to the startup.properties file:

    Copy code 
    pulse.activemq.protocol=ssl
    pulse.activemq.port=8447
    pulse.activemq.key.store.type=jks
    pulse.activemq.key.store.filename=C\:\\Program Files\\OpenText\\common\\tomcat\\9.0\\conf\\server-ssl.jks
    pulse.activemq.key.store.password=123456
    pulse.activemq.trust.store.type=jks
    pulse.activemq.trust.store.filename=C\:\\Program Files\\OpenText\\common\\tomcat\\9.0\\conf\\server-ssl.jks
    pulse.activemq.trust.store.password=123456

  5. Run this command on the server to create a server certificate:

    Copy code 
    tomcatDir/conf> keytool -export -keystore <your_keystore_file>.jks -alias <your_alias> -file <your_alias>.crt

    Example:
    C:\Program Files\OpenText\common\tomcat\9.0\conf> keytool -export -keystore server-ssl.jks -alias pulse -file pulse.crt

    The following message is displayed:

    **Certificate stored in file pulse.crt**

  6. Copy the exported pulse.crt certificate file to the <pulseAgentDataDir>\conf directory on the agent.

    Default locations:

    PulseUno version 23.4:

    		Windows C:\ProgramData\OpenText\PulseUno-Agent\conf
    UNIX/Linux /var/opt/OpenText/PulseUno-Agent/conf

    PulseUno version 23.2:

    		Windows C:\ProgramData\OpenText\Dimensions CM\Pulse Agent\conf
    UNIX/Linux /var/opt/OpenText/Pulse Agent/conf

  7. Run this command to create a new key store and a private key for the agent (if they do not exist):

    Copy code 
    pulseAgentDataDir\conf> keytool -genkey -alias <agent_alias> -keyalg RSA -keystore <agent_store_file>.jks

    Example:
    C:\ProgramData\OpenText\PulseUno-Agent\conf> keytool -genkey -alias agent -keyalg RSA -keystore agent.jks -noprompt -keypass 123456 -storepass 123456 -dname "CN=<pulse-hostname>, OU=agent, O=Company, L=Location, ST=PU, C=PU"

  8. On the agent, open the <pulseAgentDataDir>\conf\config.properties file and add the following properties:

    Copy code 
    agent.auth.mode=MUTUAL
    # For mutual authentication between pulse and agents, key store and trust store should be configured:
    agent.auth.key.store.type=jks
    agent.auth.key.store.filename=C\:\\ProgramData\\OpenText\\Dimensions CM\\Pulse Agent\\conf\\agent.jks
    agent.auth.key.store.password=123456
    agent.auth.trust.store.type=jks
    agent.auth.trust.store.filename=C\:\\ProgramData\\OpenText\\Dimensions CM\\Pulse Agent\\conf\\agent.jks
    agent.auth.trust.store.password=123456
    # Location of the PulseUno application.
    pulse.base.url=https://<pulse-hostname>:8443/pulse

  9. Run this command in the agent's conf directory to import pulse.crt:

    Copy code 
    pulseAgentDataDir\conf> keytool -import -keystore agent.jks -alias pulse -file pulse.crt

    The following message is displayed:

    **Certificate was added to keystore**

  10. Run this command in the agent's conf directory to export the agent key as a certificate:

    Copy code 
    pulseAgentDataDir\conf> keytool -export -keystore <agent_store_file>.jks -alias <agent_alias> -file <agent_alias>.crt

    Example:
    C:\ProgramData\OpenText\PulseUno-Agent\conf> keytool -export -keystore agent.jks -alias agent -file agent.crt

    The certificate is stored in this file: <agent_alias>.crt

    Before you export an agent key, you need to generate it first.

  11. Copy the exported certificate file <agent_alias>.crt to thе conf directory on the server:

    <tomcatDir>\conf

  12. To import the <agent_alias>.crt file, run this command on the server in <tomcatDir>\conf:

    Copy code 
    keytool -import -keystore server-ssl.jks -alias <agent_alias> -file <agent_alias>.crt

    The following message is displayed:

    **Certificate was added to keystore**

  13. For additional agents, repeat from step 6.

  14. Start the PulseUno server and agents.

    If you installed the agent as a service, restart the service. Otherwise, shut down the agent using the agent control script and the shutdown parameter, and then start the agent.

Back to top

See also: