...

• using HTTPS connections which are secured by private /public key keys and certificates,
• using authentication between JS7 products:
  • Option 1 (recommended):
    • applying TLS mutual authentication between JOC Cockpit and Controller as well as between Controller and Agents,
    • applying TLS mutual authentication between Director Agent instances and Subagents in an Agent Cluster.
• Note the detailed explanations in the following sections.
• • Option 2:
    • applying password authentication between JS7 products should mutual authentication not be in place.

Find examples of private.conf files for configuration configuration for download:

• Standalone Controller
  • Standalone Controller: private.conf-example-standalone-controller
• Controller Cluster
  • Primary Controller instance: private.conf-example-primary-controller
  • Secondary Controller instance: private.conf-example-secondary-controller

Standalone Controller Configuration

Client Authentication

Anchor
js7-auth-users-JOC js7-auth-users-JOC

JOC Cockpit Connections

js7 {
    auth {

# Security configuration
js7 {
    auth {
          # User accounts for HTTPShttps connections
        users {
            # ControllerHistory account IDof forJOC connectionsCockpit by primary/secondary controller instance(used to release events)
            ControllerHistory {
                distinguished-names=[
      # for use with TLS mutual authentication
              "DNQ=SOS CA, CN=controller distinguished-names=[
                    "DNQ=SOS CA, CN=joc-2-0-secondaryprimary, 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"
            # History account (used to release events)
            History {   ]

                # for use with password authentication (default password stored with JOC Cockpit Settings)
                distinguished-names=[password="sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08"
            }

        "DNQ=SOS CA, CN=joc-2-0-primary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE",
        # JOC account of JOC Cockpit (requires UpdateItem permission for deployment)
             "DNQ=SOS CA, CN=joc-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
JOC {
                # for use with TLS mutual ]authentication
                password="sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08"
distinguished-names=[
            }
        "DNQ=SOS CA, CN=joc-2-0-primary,  # JOC account (requires UpdateRepo permission for deployment)OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE",
            JOC {
       "DNQ=SOS CA, CN=joc-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
  distinguished-names=[
              ]

      "DNQ=SOS CA, CN=joc-2-0-primary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE",
   # for use with password authentication (default password stored with JOC Cockpit Settings)
     "DNQ=SOS CA, CN=joc-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
                ]
                password="sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE"

                permissions=[
                    UpdateRepoUpdateItem
                ]
            }
        }
    }
    configuration }

Explanation:

Password Authentication

Anchor
js7-auth-users-password-JOC js7-auth-users-password-JOC

JOC Cockpit Connections

js7 {
    auth {
   # directory for trusted public keys# andUser certificatesaccounts usedfor withhttps signaturesconnections
        trusted-signature-keysusers {
            # History account  PGP=${js7.config-directory}"/private/trusted-pgp-keys"
     of JOC Cockpit (used to release events)
       X509=${js7.config-directory}"/private/trusted-x509-keys"
     History   }{
    }
    journal {
        # allowfor Historyuse accountwith topassword releaseauthentication events(default topassword freestored spacewith claimedJOC byCockpit journalsSettings)
        users-allowed-to-release-events=[
        password="sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08"
    History
        ]}

      }
    web {
 # JOC account of JOC Cockpit (requires #UpdateItem keystorepermission andfor truststoredeployment)
 location for HTTPS connections
        httpsJOC {
            keystore  {
  # for use with password authentication (default password stored with JOC Cockpit Settings)
  # Default: ${js7.config-directory}"/private/https-keystore.p12"
                file=${js7.config-directory}"/private/https-keystore.p12"
password="sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE"

                key-password="jobscheduler"
permissions=[
                    store-password="jobscheduler"UpdateItem
                # alias=]
            }
        }
    }
}

Explanation:

Controller Cluster Configuration

Client Authentication

Anchor
js7-auth-users-Controller js7-auth-users-Controller

Controller Connections

js7 {
truststores=[
               auth {
        # User accounts for https connections
       # Default:users ${js7.config-directory}"/private/https-truststore.p12"
            # Controller ID for connections by primary/secondary  file=${js7.config-directory}"/private/https-truststore.p12"
                    store-password="jobscheduler"
                    # alias=
                }
            ]
        }
    }
}

...

Controller instance
            Controller {
                distinguished-names=[
                    "DNQ=SOS CA, CN=controller-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
                ]
            }
        }
    }
}

Explanation:

• Note that the Controller element name is an example that has to be replaced by the Controller ID which is specified with the 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.
  • Except for whitespace between attributes the precise sequence and values as available from the certificate's subject have to match this property value.
  • Note that the common name (CN) element in the distinguished name has to match the fully qualified domain name (FQDN) of a Controller instance's host.

  • The following command can be used to read the distinguished name from a certificate file:
    
    

    Code Block
    title Example for OpenSSL command to read a certificate's distinguished name
    # read distinguished name from the pairing Controller instance's certificate openssl x509 -in centostest-secondary.crt -noout -nameopt RFC2253 -subject # output is returned with a prefix "subject= " or similar that is not part of the distinguished name # subject= DNQ=SOS CA,CN=director-2-0-secondary,OU=IT,O=SOS,L=Berlin,ST=Berlin,C=DE

JOC Cockpit Connections

The configuration is the same as for a Standalone Controller, see JOC Cockpit Connections

Password Authentication

Anchor
js7-auth-users-password-Controller js7-auth-users-password-Controller

Controller Connections

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" Controller {
                ]password = "plain:secret"
            }
        }
    }
}

Explanation:

• This setting applies to the use of a Controller Cluster.
• Note that the Controller element name is an example that has to be replaced by the Controller ID which is specified with the 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 which can access this Controller using a Client Authentication certificate.
  • Except for whitespace between attributes the precise sequence and values as available from the certificate's subject have to match this property value.

Server Authentication

• This setting applies to the use of a Controller Cluster.

JOC Cockpit Connections

The configuration is the same as for a Standalone Controller, see JOC Cockpit Connections.

Keystore and Truststore

Settings in this section apply to both Standalone Controller and Controller Cluster instances.

Anchor
js7-web-https-keystore js7-web-https-keystore

HTTPS Keystore and Truststore Locations

...

Explanation:

• HTTPS keystore and truststore truststores are used to hold private keys and certificates.
  • Keystore and truststore settings accept the path to a file in PKCS12 format or in PEM format.
  • 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.
  • A number of truststores can be specified
• Optionally a separate HTTPS client keystore can be used:
  • The client keystore is used for HTTPS TLS mutual authentication and holds a private key and certificate created for Client Auth extended key usage. 
  • When using HTTPS TLS mutual authentication then:
    • a single certificate can be used that is generated for both 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 Server Auth key usage being stored with the HTTPS keystore and the certificate for 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:
  • 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 keystore and truststores 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 passwordtruststore are not intended for security of the configuration, they are used to verify the integrity of certificate stores as the password used for creating and reading the certificate store must be the same.
  • 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.
• The alias setting can be used for example with a keystore that holds a number of private keys from which the relevant private key is selected by its alias name.

Summary of Configuration Items

General Configuration File: controller.conf

js7.web.server: Authentication Settings

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

Security Configuration File: private.conf

...

• An additional authentication mechanism is applied when using HTTPS Server Authentication certificates or public keys for incoming connections. See below: the client of the incoming connection, e.g. JOC Cockpit,  is is required to provide a Client Authentication certificate and a password. This includes two certificates which are in place for a secure HTTPS connection: the given Controller's Server Authentication certificate and the JOC Cockpit's Client Authentication certificate.  As an alternative to Client Authentication a password can be used.
  • 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 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 has been specified with 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 Controller setting <controller-id> 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 Controller setting <controller-id> 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 UpdateItem 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 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 required as certificate based authentication is in placeis in place. However, if a password is specified then it has to match.
  • 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 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

Anchor
js7-auth-agents js7-auth-agents

js7.auth.agents: HTTPS Authentication and Authorization

• By default both Server Authentication Certificates and Client Authentication Certificates are used for HTTPS connections. If no Client Authentication Certificates 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. required that can be specified using the prefix plain:. Passwords should be quoted The same password has to be specified with the Agents private.conf configuration file.

...

• This setting is used to specify the location of a keystore and any truststores used for HTTPS connections.
• Keystore and truststore files are expected in PKCS12 format or in PEM format.
• keystore
  • The keystore includes the private key for the Controller's incoming HTTPS connectionsServer Authentication Certificate.
  • Private key types RSA and ECDSA are supported. 
  • file:  the full path to the location of the keystore file is expected.
  • key-password: Any keys included with the keystore are protected with a password. The same password has to be used for all private keys in the given keystore.
  • store-password: The keystore file is protected by a password.
  • alias: can be used for example with a keystore that holds a number of private keys from which the relevant private key is selected by its alias name.
• client-keystore
  • Use of this setting is optional. It can be used if separate certificates for Server Authentication and Client Authentication are used.
  • The Client Authentication private key and certificate can be added to this keystore.
  • Included configuration items correspond to the keystore setting.
• truststores
  
  • A truststore contains the certificates or public keys for to verify the Controller's incoming HTTPS connections.
    • Certificates are signed by a Certificate Authority (CA), alternatively a self-signed certificate can be used.
    • It is recommended that certificates are used instead of public keys.
    • Certificates of type X.509 are supported.
  • file:  the full path to the location of the truststore file is expected.
  • store-password: A truststore file is protected by a password.
  • alias: can be used for example with a truststore that holds a number of certificates from which the relevant certificate is selected by its alias name.
  • A number of truststores can be specified by repeating the file, store-password and optionally alias settings.

...

• This setting is used to specify the authentication type for HTTPS connections to a Controller.
• https-client-authentication
  
  • The value on (default) specifies that mutual authentication with certificates for Server Authentication and Client Authentication is used.
  • The value off specifies that HTTP Basic Authentication only is used.
• By default JS7 makes use of mutual authentication including both Server and Client Authentication Certificates. This setting can be switched off to use Server Authentication Certificates only.

...

• The Controller expects a signature receives signatures 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 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 medium Security Level JOC Cockpit creates the signature from the private key of the JOC Cockpit user account that deploys objects.
  • for a High 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 signatures of deployed objects.
  • X509:  specifies specifies the directory from which X.509 certificates are used to verify the signature signatures of deployed objects.

Anchor
js7-journal js7-journal

js7.journal: Journal Release Permissions

• The Controller writes a journal of events that, for example, 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 in the JOC Cockpit database. The Controller 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.

...