Secure Communication : Secure WebSocket Between Distributed Queue Agent and Central
  

Secure WebSocket Between Distributed Queue Agent and Central

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:

Securing the Communication between the Daemon and Central

Make sure that the Daemon is version 6.2.xx.
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.
The flow chart below illustrates the steps needed to enable Websocket Secure between a distributed Queue Agent and Central. These steps are described in more detail below.

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

Preconditions:

• The steps outlined in the section “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 port setting "central.websocket.secure.port" if the default port (9150) is not used.
3. Prepare, synchronize and publish the new Agent Profile.
4. In the System Administration application, open the Parameters tab and locate the Central WebSocket Server Settings section.
Change these parameters:
• Secure WebSocket enabled - true
• Secure WebSocket port - the wanted port (default 9150).
The Secure WebSocket port can not be the same as the Unencrypted WebSocket port (default: 8787).
5. Click Save to save the parameters.
6. Restart Orchestra.
7. Verify that the Queue Agent connects.

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

Preconditions:

• The steps outlined in the section “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\.
The default password is changeit.
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 conf/agent.conf file and edit the following:
• Change the setting for "central.websocket.secure" to "true".
• Change the port setting "central.websocket.secure.port" if the default port (9150) is not used.
7. Prepare, synchronize and publish the new Agent Profile.
8. In the System Administration application, open the Parameters tab and locate the Central WebSocket Server Settings section.
Change these parameters:
• Secure WebSocket enabled - true
• Secure WebSocket port - the wanted port (default 9150).
The Secure WebSocket port can not be the same as the Unencrypted WebSocket port (default: 8787).
9. Click Save to save the parameters.
10. Restart Orchestra.

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.
3. Click Save to save the changes.
4. Restart Orchestra.
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.