Introduction

The article is focused on configuration items used for HTTPS Server and Client Authentication. For a complete overview of settings see JS7 - Controller Configuration Items and JS7 - Agent Configuration Items,

• 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 HTTP client could perform a man-in-the-middle attack e.g. by by, for example, pretending to be a Controller that connects to an Agent.
• Consider the communication scheme between JS7 products as explained in the JS7 - System Architecture article:
  
  • User browsers acting as HTTP clients establish connections to the JOC Cockpit as an HTTP server.
  • The JOC Cockpit acting as an HTTP client establishes connections to Controller instances acting as HTTP servers.
  • Controller instances acting as HTTP clients establish connections to Agents acting as HTTP servers.

...

Configuration File: JS7_CONTROLLER_CONFIG_DIR/private/private.conf

DownloadFind an example for Controller configuration for download:  private.conf

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=[
                    UpdateItem
                ]
            }
        }
    }

    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"
                # alias
            }
            truststores=[
                {
                    # Default: ${js7.config-directory}"/private/https-truststore.p12"
                    file=${js7.config-directory}"/private/https-truststore.p12"
                    store-password="jobscheduler"
                    # alias=
                }
            ]
        }
    }
}

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 being used.
• The configuration items relevant to mutual authentication from the example above are described below.

...

js7 {
    auth {
        # User accounts for HTTPS connections
        users {
            # 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 UpdateRepoUpdateItem 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=[
                    UpdateItem
                ]
            }
        }
    }
}

...

• The Controller verifies the signature of deployable objects such as workflows. This can be performed for PGP signatures and X.509 signatures. 
• The trusted-signature-keys setting specifies the locations for PGP public keys and for X.509 certificates.
• If either PGP public keys or X.509 certificates are not used then the relevant setting should not be specified as it implies that the indicated directory will be populated with public keys or certificates accordingly.

Services entitled to release events from the Controller

...

journal

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

...

• The journal holds e.g. information about order state transitions. This information is consumed by the JS7 - History Service that updates the JS7 database from this information.
• The Controller's journal would grow if entries that have been consumed by the History Service could not be released. The users-allowed-to-release-events setting specifies the names, e.g. History, of the accounts for which authentication settings are indicated from the js7.auth.users section.
• A single History account is used with any number of JOC Cockpit instances. If more than one consumer account was to be specified then all consumers would have to confirm having received order transition events before such events could be removed from the journal.

HTTPS Keystore and Truststore

...

Access

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

Explanation:

• HTTPS keystores and 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.
  • A keystore holds the Controller instance's private key and certificate. This information is used for:
    • Server Authentication with JOC Cockpit and for
    • Client Authentication with Agents.
  • A truststore holds the certificate(s) used to verify:
    • Client Authentication certificates presented by JOC Cockpit and
    • Server Authentication certificates presented by Agents.
  • Any number of truststores can be used.
• 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 Client Auth extended key usage.
  • When using HTTPS mutual authentication then:
    • a single certificate can be used that is generated for both Server Auth and Client Auth extended key usages. 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 in the HTTPS keystore and the certificate for Client Auth key usage being stored in 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,
  • a password for access to the truststore can be specified.
• Passwords for keystores keystore and truststores do not tend to improve the configuration security: 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 setting 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.

...

Configuration File: JS7_AGENT_CONFIG_DIR/private/private.conf

Download: Find an example for Agent configuration for download: private.conf

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-primary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE",
                    "DNQ=SOS CA, CN=controller-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
                ]
            }
        }
    }

    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"
                # store-passwordalias=jobscheduler
            }
            truststores=[
                {
                    # Default: ${js7.config-directory}"/private/https-truststore.p12"
                    file=${js7.config-directory}"/private/https-truststore.p12"
                    store-password="jobscheduler"
                    # alias=
                }
            ]
        }
    }
}

Explanation:

• The configuration file is located in the JS7_AGENT_CONFIG_DIR/private folder.
• Note that the Controller element name is an example that has to be replaced by the Controller ID which is specified with the same value during installation of both Controller instances in a cluster.
• Note that the above configuration has to be deployed to all Agent instances.
• The configuration items relevant to mutual authentication from the example above are described below.

...

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-primary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE",
                    "DNQ=SOS CA, CN=controller-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
                ]
            }
        }
    }
}

Server Authentication

HTTPS Keystore and Truststore Locations

See the JS7 - Agent Configuration Items#js7-web-https-keystore article for an explanation of the setting.

js7 {
    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"
                # alias=
            }
            truststores=[
                {
                    # Default: ${js7.config-directory}"/private/https-truststore.p12"
                    file=${js7.config-directory}"/private/https-truststore.p12"
                    store-password="jobscheduler"
                    # alias=
                }
            ]
        }
    }
}

Signed Scheduling Objects

...