Introduction
- HTTPS Server Authentication is preferably used in combination with Client Authentication (mutual authentication) as this allows a secure configuration without the use of passwords.
- The purpose of Server Authentication is to secure the identity of an HTTP server and to encrypt the communication between client and server.
- The purpose of Client Authentication is to prove the identity of a client. Without proof of identity any HTTP client could perform a man-in-the-middle attack by, for example, pretending to be a Controller that connects to an Agent.
- Please refer to the communication scheme between JS7 components as described in the JS7 - System Architecture article:
- User browsers acting as HTTPS clients establish connections to JOC Cockpit as an HTTPS server.
- JOC Cockpit acting as an HTTPS client establishes connections to Controller instances acting as HTTPS servers.
- Controller instances acting as HTTPS clients establish connections to Agents acting as HTTPS servers.
- We recommend applying mutual authentication. However, there might be reasons why use of Client Authentication is not an immediate option, for example:
- Use of a wildcard certificate for Server Authentication leverages the effort for certificate management. At the same time such certificates cannot be used for Client Authentication.
- If mutual authentication is not an immediate option then passwords can be used by following the recommendations made in this article.
Location of Configuration Files
In the following the JS7_CONTROLLER_CONFIG_DIR
placeholder specifies the configuration directory of the Controller. The JS7_AGENT_HOME
, JS7_AGENT_CONFIG_DIR
placeholders specify the directories where the Agent is installed and configured.
JS7_CONTROLLER_CONFIG_DIR
is the Controller's configuration directory that is specified during installation:<extraction-directory/controller/var/config
(default on Unix/Windows for JS7 - Controller - Headless Installation on Linux/Windows)C:\ProgramData\sos-berlin.com\js7\controller\config
(default on Windows for JS7 - Controller - Installation Using the Windows Graphical Installer)
JS7_AGENT_HOME
is the installation path that is specified during the JobScheduler Agent installation:<extraction-directory>/agent
(default on Unix/Windows for JS7 - Agent - Headless Installation on Unix/Windows)C:\Program Files\sos-berlin.com\js7\agent
(default on Windows for JS7 - Agent - Installation Using the Windows Graphical Installer)
JS7_AGENT_CONFIG_DIR
is the Agent's configuration directory that is specified during Agent installation:<extraction-directory>/agent/var_<port>/config
(default on Unix/Windows for JS7 - Agent - Headless Installation on Unix/Windows)C:\ProgramData\sos-berlin.com\js7\agent\config
(default on Windows for JS7 - Agent - Installation Using the Windows Graphical Installer)
Controller Configuration
Configuration File: JS7_CONTROLLER_CONFIG_DIR/private/private.conf
Download: private.conf
Explanation:
- The configuration file is located in the
JS7_CONTROLLER_CONFIG_DIR/private
folder. - Note that the above configuration has to be deployed to both Controller instances if a Controller Cluster is to be used.
- The configuration items relevant to Server Authentication from the example above are described in the following sections.
Specify Agent ID and Password
js7 { auth { # for each Agent specify Agent ID and plain text password for authentication agents { agent-dev-001="secret" agent-dev-002="secret" } } }
Explanation:
- The Agent ID for each Agent is specified according to the pattern
agent-dev-001
. An Agent is assigned a unique Agent ID during initial operation with JOC Cockpit that cannot be changed unless an Agent's journal is dropped. - The plain text password
secret
is specified.
Disable Client Authentication
js7 { web { # disable use of client authentication certificates server { auth { https-client-authentication=off } } }
Explanation:
- By default Client Authentication is used if Server Authentication is in place.
- The above setting disables Client Authentication.
Agent Configuration
Configuration File: JS7_AGENT_CONFIG_DIR/private.conf
Download: private.conf
Explanation:
- The configuration file is located with the
JS7_AGENT_CONFIG_DIR/private
folder. - Consider that the above configuration has to be deployed to any Agent instances.
- The configuration items relevant to Server Authentication with passwords from the example above are described in the following sections.
Specify Controller ID and Password
js7 { auth { # User accounts for https connections users { # Controller ID for connections by primary/secondary Controller instance js7_dev { password="plain:secret" # password="sha512:$JhbM9ClpBpH2oB2O$qmWRbhOAfNHbmz3bp1AV.ATV0WIKVdZp3ceVXJZc.GHX4L7/iWJB7RGpzjZ2JzvbdPBtlpCFy8CLvYpKoBBKP/" } } }
Explanation:
- In this example
js7_dev
is the Controller ID used by a Standalone Controller or by a Controller Cluster. A Controller is assigned a unique Controller ID during installation. The Controller ID cannot be changed unless the Controller's journal is reset. - The
password
for the Controller ID in the Agent configuration is the same as stated in the Controller configuration.- The password has to be preceded with
plain:
if a plain text password is used. - The password has to be preceded with
sha512:
if a password hashed with this algorithm is used- There are a number of ways to create sha512 hash values from passwords.
- One possible solution includes using:
openssl passwd -6
- The password has to be preceded with
Disable Client Authentication
js7 { web { # disable use of client authentication certificates server { auth { https-client-authentication=off } } }
Explanation:
- By default Client Authentication is used if Server Authentication is in place.
- The above setting disables Client Authentication.
Overview
Content Tools