Introduction

• Controllers makes make use of two configuration files:
  • the general configuration file controller.conf that is available from at the following locations:
    • Windows: C:\ProgramData\sos-berlin.com\js7\controller\var\config\controller.conf
    • Unix /var/sos-berlin.com/js7/controller/var/config/controller.conf
  • the security configuration from private.conf that is available from at the following locations:
    • Windows: C:\ProgramData\sos-berlin.com\js7\controller\var\config\private.conf
    • Unix: /var/sos-berlin.com/js7/controller/var/config/private/private.conf
  • The configuration format makes use of Typesafe Config, see JS7 - Configuration Format
  • Controller instances have to be restarted in order to apply changes to the configuration files.
• For HTTPS configuration consider please refer to the JS7 - Configuration Templates article.

Default Configuration

General Configuration File: controller.conf

...

• This setting specifies public access to a Controller if incoming HTTP connections are to be used. If used with a value true then no authentication is not applied.
• Default: false

Anchor
js7-journal-cluster js7-journal-cluster

Controller Cluster Configuration

...

• A Secondary Controller instance specifies this setting to indicate that this instance starts as a standby node (Backup). Without When this setting being is not in place, both instances of a Controller Cluster will start as standalone instances.
• This setting is relevant for initial operation only. It is independent of which Controller instance later on will be the active one and which instance will be the standby instanceone.
• This setting has to be added by the user before start of starting a Secondary Controller.

• This setting is used for Controller instances in cluster mode only, it is not used for standalone Controller instances.
• The registration of Primary and Secondary Controller instances is performed by the JOC Cockpit during initial operation.
  • Therefore the only setting required for cluster operation is is:
    • js7.journal.cluster.node.is-backup=yes: For a Secondary Controller instance this setting specifies that during initial operation the given instance will be the inactive standby node.
  • Additional settings can be applied. However, however, we recommend to use that the JOC Cockpit is used instead.
    • nodes
      • Primary, Backup: For a Primary Controller instance this setting specifies the URLs of the Primary and Backup (Secondary) instance. The URL includes specification of the protocol http/https protocol, the hostname and port.
    • watches
      • Watches are Agents in a JS7 environment that are involved in the decision about a fail-over situation. If Controller instances in a cluster are not connected to each other any longer, e.g. due to network errors, then the majority of Agents decides if a fail-over should take place.
      • At least one Agent has to be specified by its URL.

...

The Controller requires X.509 certificates and/or PGP public keys to be in place. These are used to verify the signatures of signed workflows. Unsigned workflows are will not be accepted by a Controller and are will not be forwarded to Agents, therefore . Therefore a minimum of one X.509 certificate file or PGP public key file has to be present in the directories that are specified with the following configuration item:

...

• The Controller verifies the signature of deployable objects such as workflows. This can be performed for using PGP signatures and for X.509 signatures. 
• The trusted-signature-keys setting specifies the location of PGP public keys and X.509 certificates.
• If no PGP public keys are used or if no X.509 certificates are used then the respective this setting should not be used as it expects is expected that the indicated directory to be is populated with public keys or certificates respectively.

...

It is essential to secure the connections between Controller, Agents and JOC Cockpit. This includes:

• using HTTPS connections that which are secured by private/public key and certificates,
• applying mutual authentication between JOC Cockpit and Controller as well as between Controller and Agent.
• Consider Note the detailed explanations from in the subsequent chaptersfollowing sections.

# Security configuration
js7 {
    auth {
        # User accounts for HTTPS connections
        users {
            # Controller ID for connections by primary/secondary controller instance
            Controller {
                distinguished-names=[
                    "DNQ=SOS CA, CN=controller-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
                ]
            }
            # History account (used to release events)
            History {
                distinguished-names=[
                    "DNQ=SOS CA, CN=joc-2-0-primary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE",
                    "DNQ=SOS CA, CN=joc-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
                ]
                password="sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08"
            }
            # JOC account (requires UpdateRepo permission for deployment)
            JOC {
                distinguished-names=[
                    "DNQ=SOS CA, CN=joc-2-0-primary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE",
                    "DNQ=SOS CA, CN=joc-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
                ]
                password="sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE"
                permissions=[
                    UpdateRepo
                ]
            }
        }
    }
    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 events to free space claimed by 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
                }
            ]
        }
    }
}

...

Explanation:

• This setting applies to the use of a Controller Cluster.
• Consider Note that the element name  Controller element name is an example that has to be replaced by the Controller ID that which is specified with the same value identical values during installation of both the Controller instances in a cluster.
• The distinguished-names setting indicates the subject of the pairing Controller's Client Authentication certificate. The certificate and subject authenticate the pairing Controller without use of passwords.
  • The Controller configuration specifies the distinguished name of the pairing Controller that which can access this Controller by use of using a Client Authentication certificate.
  • Except for whitespace between attributes the precise sequence and values as available from the certificate's subject has have to match this property value.

...

• HTTPS keystore and truststore are used to hold private keys and certificates.
  • The keystore holds the Controller instance's private key and certificate. This information is used:
    • for Server Authentication with the JOC Cockpit and
    • for Client Authentication with Agents.
  • The truststore holds the certificate(s) used to verify:
    • Client Authentication certificates presented by the JOC Cockpit and
    • Server Authentication certificates presented by Agents.
• Optionally a separate HTTPS client keystore can be used:
  • The client keystore is used for HTTPS mutual authentication and holds a private key and certificate created for the extended for Client Auth extended key usage Client Auth. 
  • When using HTTPS mutual authentication then:
    • a single certificate can be used that is generated for both extended key usages Server Auth and Client Auth extended key use. In this case do not use the HTTPS client keystore but use the HTTPS keystore to hold the certificate.
    • separate certificates can be used with the certificate for key usage for Server Auth key usage being stored with the HTTPS keystore and the certificate for key usage Client Auth key use being stored with the HTTPS client keystore.
  • For details see 

    Jira
    server SOS JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 6dc67751-9d67-34cd-985b-194a8cdc9602 key JS-1959

• Keystore and Truststore locations are specified. In addition:
  • for the keystore a password for the private keys included in the keystore and a password for access to the keystore can be specified
  • for the truststore a password for access to the truststore can be specified.
• Passwords for keystores and truststores have no tendency do not tend to improve security of the configuration: the passwords have to be specified as plain text and have to be in reach of the Controller. This mechanism is not too different from hiding the key under your doormat. In fact limiting ownership and access permissions for keystore and truststore files to the JS7 Controller's run-time account are more important than using a password.
  • The key-password is used for access to a private key in a keystore.
  • The store-password setting is used for access to a keystore or to a truststore.
  • For PKCS12 (*.p12) keystores both settings have to use the same value. The settings can be omitted if no passwords are used.

...

• This setting specifies public access to a Controller if insecure HTTP connections are to be used. If used with the value true then no HTTP Server Authentication is not applied.
• Default: false

Security Configuration File: private.conf

...

• An additional authentication mechanism is applied when using HTTPS Server Authentication certificates or public keys for incoming connections, see . See below: the client of the incoming connection, e.g. JOC Cockpit, is required to provide a Client Authentication certificate and a password. This includes two certificates that which are in place for a secure HTTPS connection: the given Controller's Server Authentication certificate and the JOC Cockpit's Client Authentication certificate. 
  • The fact that a given certificate is to be used for Server Authentication and/or Client Authentication is specified with the key usage when the certificate is being created and signed.
  • The distinguished name that is specified with the Controller's configuration has to match the Client Authentication Certificate's or Client public key's subject attribute. This attribute specifies the hostname and additional information that is created when the certificate or public key is generated.
• <controller-id>
  • This element holds the Controller ID that is has been specified with the same value identical values during installation of both Controller instances in a cluster.
  • Settings in this section are used for connections from a pairing Controller instance, e.g. for a Secondary Controller instance if the given configuration is used for the Primary Controller instance and vice versa. 
  • distinguished-names
    • Specifies the distinguished name as given with the subject of the Client Authentication Certificate for incoming HTTPS connections of a pairing Controller instance.
    • Any number of distinguished names can be specified allowing a number of incoming HTTPS connections from different Controller instances. At a given point in time only one pairing Controller instance can connect to the given Controller.
    • Except for whitespace between attributes the precise sequence and values as available from the certificate's subject has to match this property value.
• History
  • Settings in this section are used for the History Service of JOC Cockpit instances that access the given Controller.
  • distinguished-names:  the same applies as for the above  Controller setting described above. The JOC Cockpit Client Authentication certificate is used.
  • password: a symmetric password that is used for authentication of the History Service to the Controller for both HTTP and HTTPS connections, see below.
• JOC
  • Settings in this section are used for services running in JOC Cockpit instances that access the given Controller.
  • distinguished-names:  the same applies as for the above  Controller setting described above. The JOC Cockpit Client Authentication certificate is used.
  • password: a symmetric password is used for authentication of the History Service to the Controller for both HTTP and HTTPS connections, see below.
  • permissions: JOC Cockpit requires the UpdateRepo permission to enable users to deploy objects such as workflows.
• The password is used for authentication of the History and JOC service accounts with the Controller. Both accounts are typically are running in the same JOC Cockpit instance. 
  
  • If HTTP connections are used then the password is the only means for authentication. If HTTPS connections with mutual authentication are used then the password is not relevant as certificate based authentication is in place.
  • The password is specified with the section joc of the JS7 - Settings page of JOC Cockpit and in the private.conf file.
    • User Input to the Settings page of JOC Cockpit can look like this:
      
      
      
      Input to the GUI simply accepts the password and does not require to use the prefixes sha512: or plain:.
    • In the private.conf file a hashed value or a plain text value can be specified like this:
      • password="sha512:B793649879D6..."
      • password="plain:JS7-History"
  • If the password is modified in the private.conf file then it also has to be modified in the JOC Cockpit settings too to make the passwords match.
  • The password setting cannot be omitted, however, an empty password can be specified, for example with mutual authentication HTTPS connections, like this:
    • password="plain:"
  • If the password is modified in the private.conf file then it has to be modified in the JOC Cockpit settings too to make the passwords match.
  • The password setting cannot be omitted, however, an empty password can be specified, for example with mutual authentication HTTPS connections, like this:
    • password="plain:"
  • From the private.conf file that ships by default the plain text value and the hashed values are:
    • History: 
      • Plain Text: JS7-History
      • Hash: sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08
    • JOC:
      • Plain Text: JS7-JOC
      • Hash: sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE

...

• By default for HTTPS connections both Server Authentication Certificates and Client Authentication Certificates are used for HTTPS connections. If no Client Authentication Certificates should are to be used then the Controller has to use a password to authenticate with an Agent.
• For each Agent the <Agent ID> and a plain text password is specified. A plain-text password is required. The same password has to be specified with the Agents private.conf configuration file.

...

• The Controller expects a signature Fof for any deployed objects such as workflows. Such signatures are created with a private key and are verified by the Controller based on the available certificates. Agents perform similar signature verification and are configured accordingly.
• When deploying objects with JOC Cockpit:
  • for a Low Security Level JOC Cockpit creates the signature from a single private key that is used for any JOC Cockpit user accounts allowed to deploy objects.
  • for a Medium Security Level JOC Cockpit creates the signature from the private key of the JOC Cockpit user account that deploys objects.
  • for a High Security Level the user creates the signature outside of JOC Cockpit and uploads the signed objects.
• The Controller supports PGP public keys and X.509 certificates. This setting expects a directory that holds a number of public key files or certificate files.
• trusted-signature-keys
  • PGP: specifies the directory from which PGP public keys are used to verify the signature of deployed objects.
  • X509: specifies the directory from which X.509 certificates are used to verify the signature of deployed objects.

...

• The Controller writes a journal of events that, for example, results result from order state transitions such as an order starting, failing, completing etc.
• The journal file will grow indefinitely if events are not released. Typically events are consumed by the JOC Cockpit and are added to the order and task history. Events are released from the Controller's journal once they have been stored persistently to in the JOC Cockpit database. The Controller accordingly will then free the space consumed by its journal files.
• users-allowed-to-release-events:  specifies the list of accounts that are allowed to send a command to the Controller to release events.
  • Typically the "History" account is specified, this account is used by JOC Cockpit.
  • If more than one account is specified then events are released only after all accounts have sent the command to release events to the Controller.

...