Secure communication between Central and distributed Queue Agent

This section is only applicable if using a distributed Queue Agent!

In this scenario, we will secure the communication between a distributed Queue Agent and Orchestra Central, as highlighted in the following picture:

Note that you need to secure the communication between the Daemon and Central. Make sure that the Daemon is version 6.2.xx or later. Since the Daemon component in a distributed Queue Agent cannot be upgraded as part of a remote upgrade, special considerations are required:

• If running on Hub or BranchHub, a firmware patch is required to make the Daemon able to communicate securely with Central.

The Daemon will use the settings configured in agent.conf for this purpose, more precisely the following settings: "central.websocket.secure", "central.websocket.secure.port" and "jetty.jvm.args".

• If running the distributed Queue Agent on a PC or similar, the easiest way is to replace the entire Queue Agent distribution with a newer version.

Apply the necessary upgrades and then continue with the configuration steps below for the distributed Queue Agents, which will enable secure communications for both Daemon and jiql.

Enable WebSocket Secure between Central and distributed Queue Agent

The flow chart below illustrates the steps needed to enable Websocket Secure between Central and distributed Queue Agent. These steps are described in more detail below.

1b & 2b: Certificate Verified by a Public CA

• The steps outlined in the section “Enable HTTPS for Orchestra Central” have been performed.

• Section “Disabling Unencrypted WebSocket Communications” should have been read through and considered.

1. Copy the existing Agent Profile to a separate folder, such as tmp.

2. Open the conf/agent.conf file and edit the following:

• Change the setting for "central.websocket.secure" to "true".

• Change the setting "central.websocket.secure.port" to the wanted port. Default is 9150.

3. In the System Administration application, open the Parameters tab and locate the Central WebSocket Server Settings section.

The Secure WebSocket can not be the same as the Unencrypted WebSocket (default: 8787).

4. Prepare, synchronize and upgrade the new Agent Profile.

1a & 2a: Certificate NOT Verified by a Public CA

• The steps outlined in the section “Enable HTTPS for Orchestra Central” have been performed.

• Section “Disabling Unencrypted WebSocket Communications” should have been read through and considered.

We recommend using a tool such as Keystore Explorer, http://keystore-explorer.org/, for managing your keystores and truststore.

1. In Keystore Explorer, open the file keystore.jks, located in <installation directory>\conf\security\. The default password is changeit.

2. Right-click and select Export -> Export Certificate Chain. Click Export.

3. In Keystore Explorer, open the file truststore.jks, located in <installation directory>\media\agentProfiles\<your_agent_profile>\conf\security\.

4. Select Tools -> Import Trusted Certificate and import the *.cer file that you exported above.

Do not forget to click Save

5. Copy the existing Agent Profile to a separate folder, such as tmp.

6. Open the <installation directory>\ media\ agentProfiles\ <your_agent_profile>\ conf/ agent.conf file and edit the following:

• Change the setting for "central.websocket.secure" to "true".

• Change the setting "central.websocket.secure.port" to the wanted port. Default is 9150.

7. In the System Administration application, open the Parameters tab and locate the Central WebSocket Server Settings section.

• Secure WebSocket port - the wanted port (default is 9150).

The Secure WebSocket port can not be the same as the Unencrypted WebSocket port (default: 8787).

8. Prepare, synchronize and upgrade the new Agent Profile.

Disabling Unencrypted WebSocket Communications

Make sure that your Queue Agent is successfully connected before you disable unencrypted WebSocket communications.

1. In the System Administration application, open the Parameters tab and locate the Central WebSocket Server Settings section.

2. Uncheck the check box for the parameter WebSocket enabled.

If there are distributed Queue Agents in the setup that have not yet been configured to use secure WebSocket communication, they will stop working properly and it will not be able to e.g. remote upgrade them to support secure communications.

This is especially important for distributed Queue Agents that run on Hub or BranchHub, as they require a firmware patch to add support for secure WebSocket communication to the Daemon component. See Disabling Unencrypted WebSocket Communications above.

Disabling unencrypted WebSocket will make it impossible for software running on other machines to communicate with the Central system using unencrypted communication.

However, the unencrypted channel will not be 100% disabled, it will simply start to listen on the localhost / 127.0.0.1 network interface only.

The reason for this is that the Central Queue Agent still uses unencrypted communication to Central.

Enable HTTPS between Queue Agents and Central

The following flow chart illustrates the steps needed to enable HTTPS for HTTP communication between Queue Agents and Central. The steps are described in more detail below:

1. In the System Administration application, open the Parameters tab and locate the Central Access Parameters section:

2. Select https as Central HTTP Protocol and Central HTTP Port to 8443.

3. Save the Parameters and restart the Orchestra service.