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

js7 {
    auth {
        # User accounts for HTTPS connections
        users {
            # Controller ID for connections by primary/secondary Controller instance
            js7_dev {
            }
            # History account (used to release events)
            History {
                password="sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08"
            }
            # JOC account (requires UpdateRepo permission for deployment)
            JOC {
                password="sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE"
                permissions=[
                    UpdateItem
                ]
            }
        }

        # for each Agent specify Agent ID and plain text password for authentication
        agents {
           agent-dev-001="secret"
           agent-dev-002="secret"
        }
    }

    configuration {
        # directory for trusted public keys and certificates used with signatures
        trusted-signature-keys {
            PGP=${js7.config-directory}"/private/trusted-pgp-keys"
            X509=${js7.config-directory}"/private/trusted-x509-keys"
        }
    }

    journal {
        # allow History account to release unused journals
        users-allowed-to-release-events=[
            History
        ]
    }

    web {
        # keystore and truststore location for https connections
        https {
            keystore {
                # Default: ${js7.config-directory}"/private/https-keystore.p12"
                file=${js7.config-directory}"/private/https-keystore.p12"
                key-password=jobscheduler
                store-password=jobscheduler
            }
            truststores=[
                {
                    # Default: ${js7.config-directory}"/private/https-truststore.p12"
                    file=${js7.config-directory}"/private/https-truststore.p12"
                    store-password=jobscheduler
                }
            ]
        }

        # disable use of client authentication certificates
        server {
            auth {
                https-client-authentication=off
            }
        }
    }
}

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

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/"
            }
        }
    }
    
    configuration {
        # Locations of certificates and public keys used for signature verification
        trusted-signature-keys {
            PGP=${js7.config-directory}"/private/trusted-pgp-keys"
            X509=${js7.config-directory}"/private/trusted-x509-keys"
        }
    }
    
    job {
        # Enable script execution from signed workflows
        execution {
            signed-script-injection-allowed = yes
        }
    }
    
    web {
        # Locations of keystore and truststore files for HTTPS connections
        https {
            keystore {
                # Default: ${js7.config-directory}"/private/https-keystore.p12"
                file=${js7.config-directory}"/private/https-keystore.p12"
                key-password=jobscheduler
                store-password=jobscheduler
            }
            truststores=[
                {
                    # Default: ${js7.config-directory}"/private/https-truststore.p12"
                    file=${js7.config-directory}"/private/https-truststore.p12"
                    store-password=jobscheduler
                }
            ]
        }

        # Disable use of client authentication certificates
        server {
            auth {
                https-client-authentication=off
            }
        }
    }
}

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

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.