Introduction

• An Agent makes use of two configuration files:
  • the general configuration file agent.conf that is available from the following locations:
    • Windows: C:\ProgramData\sos-berlin.com\js7\agent\var\config\agent.conf
    • Unix /var/sos-berlin.com/js7/agent/var/config/agent.conf
  • the security configuration file private.conf that is available from the following locations:
    
    • Windows: C:\ProgramData\sos-berlin.com\js7\agent\var\config\private.conf
    • Unix: /var/sos-berlin.com/js7/agent/var/config/private/private.conf
  • The configuration format makes use of Typesafe Config, see JS7 - Configuration Format
  • Restart the Agent instance to apply changes to any configuration file.
• For HTTPS configuration consider the JS7 - Configuration Templates

Default Configuration

General Configuration File: agent.conf

HTTP Connections

By default the Agent configuration ships with HTTP connections enabled. It is recommended that public/private keys and certificates for secure HTTPS communication are used and that HTTP connections are disabled.

# Allow http connections without authentication
js7.web.server.auth.public = true

Security Configuration File: private.conf

Directory for Trusted Certificates used to verify Signed Workflow Signatures

The Agent 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 not accepted by an Agent, 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:

# Security configuration
js7 {
    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"
        }
    }

Explanation:

• The Agent verifies the signature of deployable objects such as workflows. This can be performed for 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 setting should not be used as it expects the indicated directory to be populated with public keys or certificates respectively.

Script Execution from Signed Workflows

The default Agent configuration allows job scripts that include shell commands to be executed from any location. Without this setting scripts are restricted to being executed from the Agent's config/executables directory only.

# Allow jobs from signed workflows to execute shell commands
js7.job.execution.signed-script-injection-allowed = yes

Secure Configuration

It is essential that the connections between Controller and Agents are secured. This includes

• to use HTTPS connections that are secured by private keys and certificates,
• to apply mutual authentication between Controller and Agent.
• Consider detailed explanations from the subsequent chapters.

# Security configuration
js7 {
    auth {
        # User accounts for https connections
        users {
            # Controller account 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
            }
            truststores=[
                {
                    # Default: ${js7.config-directory}"/private/https-truststore.p12"
                    file=${js7.config-directory}"/private/https-truststore.p12"
                    store-password=jobscheduler
                }
            ]
        }
    }
}

Client Authentication

Controller Connections

js7 {
    auth {
        # User accounts for https connections
        users {
            # Controller account 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"
                ]
            }
        }
    }
}

Explanation:

• This setting applies to use of an Agent with a solo Controller or with a Controller Cluster.
• This setting specifies the distinguished name indicated with the Controller's Client Authentication certificate. The certificate acts as a replacement for a password.
  • The Agent configuration specifies the distinguished names of any Controllers that access the Agent by use of a Client Authentication certificate.
  • Consider that the common name (CN) setting in the distinguished name has to match the fully qualified domain name (FQDN) of a Controller's host.

Server Authentication

HTTPS Keystore and Truststore Locations

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

Explanation:

• HTTPS keystore and truststore are used to hold private keys and certificates
  • The keystore holds the Agent's private key and certificate. This information is used
    • for Server Authentication with JOC Cockpit and
    • for Client Authentication with Agents.
  • The truststore holds the certificate(s) used to verify
    • Client Authentication certificates presented by a Controller and
    • Server Authentication certificates challenged by pairing Controllers.
• Keystore and Truststore locations are specified. In addition,
  • for the keystore a password for the private keys included 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 to improve security of the configuration: the passwords have to be specified as plain text and have to be in reach of the Agent. 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 Agent's run-time account are more important than using a password.
  • The key-password is used for access to a private key in 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 Items

General Configuration File: agent.conf

js7.web.server: Authentication Settings

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

Security Configuration File: private.conf

js7.job.execution: Script Execution Permissions

• By default the Agent prevents any commands and scripts from being executed except for scripts located in specific directories. This setting allows any commands and scripts to be executed that the workflow has signed and the signature has been verified.

js7.configuration: Trusted Signature Keys

• The Agent expects a signature for any deployed objects such as workflows. Such signatures are created with a private key and are verified by the Agent according to the available certificates. 
• 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 Agent 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.

js7.auth.users: HTTPS Authentication and Authorization

• An additional authentication mechanism is applied when using HTTPS certificates or public keys for incoming connections, see below: the client of the incoming connection, i.e. a Controller, is required to provide a Client Authentication Certificate. This includes two certificates that are in place for a secure HTTPS connection: the Agent's Server Authentication Certificate and the Controller'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 Agent's configuration has to match the Client Authentication Certificate's subject attribute of a Controller. This attribute specifies the hostname and additional information that is created when the certificate or public key is generated.
• Controller
  • Settings in this section are used for incoming HTTPS connections from Controller instances.
  • distinguished-names: 
    • Specifies the distinguished name as given with the subject of the Client Authentication Certificate for incoming HTTPS connections from a Controller.
    • Any number of distinguished names can be specified allowing a number of incoming HTTPS connections from different Controllers.

js7.web.https: HTTPS Certificates

• 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 PKCS#12 format.
• keystore
  • The keystore includes the private key for the Agent's incoming HTTPS connections.
  • Private key types RSA and ECDSA are supported. 
  • file:  the full path to the location of the keystore file is expected.
    • Default: ${js7.config-directory}"/private/https-keystore.p12"
  • 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.
• truststores
  
  • A truststore contains the certificates or public keys for the Agent'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.
    • Default: ${js7.config-directory}"/private/https-truststore.p12"
  • store-password: A truststore file is protected by a password.
  • A number of truststores can be specified by repeating the file and store-password settings.

js7.web.server: HTTPS Authentication

• This setting is used to specify the authentication type for HTTPS connections to an Agent.
• 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.