Introduction
- Users benefit from the certificate authority included with JOC Cockpit to create and to roll-out private keys and certificates.
- This includes simplified roll-out to Controller and Agent instances to establish secure HTTPS connections.
- The build-in certificate authority is applicable when operating JOC Cockpit in a low or medium security level, see JS7 - Security Architecture.
- The built-in certificate authority
- creates X.509 certificates for HTTPS Mutual Authentication
- between JOC Cockpit and Controller instances,
- between Primary and Secondary Controller instances,
- between Controller instances and Agents.
- is not used to create server authentication certificates for access to JOC Cockpit. Access is performed by user browsers, therefore it is preferable to use a server authentication certificate that is signed by a known certificate authority for which user browsers include the root certificate.
- creates X.509 certificates for HTTPS Mutual Authentication
- Users benefit from simplified rollout of private keys and certificates when using the built-in certificate authority.
JS7 provides a Command Line Client available with Controller and Agents instances to create and to roll-out private keys and certificates using the built-in certificate authority. Rollout of private keys and certificates created with an external certificate authority are not in scope of the Command Line Client. The functionality includes
- to authenticate with JOC Cockpit by use of a security token, see JS7 - Certificate Authority - Manage Certificates with JOC Cockpit,
- to request a private key and certificate to be created by JOC Cockpit on-the-fly,
- to update a Controller or Agent instance's configuration for use of the private key and certificate with HTTPS mutual authentication.
Prerequisites
The following conditions have to be met before the Command Line Client can be used to roll-out private keys and certificates.
- The JOC Cockpit certificate authority has to be available and the root private key and certificate have been created.
- Valid security tokens have been generated with JOC Cockpit for the desired Controller and Agent instances.
- For details see JS7 - Certificate Authority - Manage Certificates with JOC Cockpit
Certificate Rollout
Rollout of certificates includes to perform the following steps
- JOC Cockpit
- The JOC Cockpit certificate authority has to be available and the Root CA private key and certificate have been created.
- Valid security tokens have been generated with JOC Cockpit for the Controller and Agent instances that require a certificate.
- For details see JS7 - Certificate Authority - Manage Certificates with JOC Cockpit
- Controller/Agent Instance
- Both components include the Certificate Rollout Client that is available from the Controller/Agent Instance Start Script.
- The Certificate Rollout Client connects to JOC Cockpit. Authentication is performed by use of the one-time security token generated with the previous step.
- The JOC Cockpit certificate authority is requested to create a private key and server/client certificate for the specified host. Private key and certificate are created on-the-fly and are returned to the Certificate Rollout Client. In addition, JOC Cockpit stores the certificate with its database. The Certificate Rollout Client
- stores the private key in a keystore file,
- stores the server/client certificate in a truststore file,
- updates the configuration in the
./config/private/private.conf
file.
Certificate Rollout Client
The Controller/Agent Instance Start Script for Unix and Windows includes the Certificate Rollout Client and is available from the following locations:
- for a Controller instance:
./bin/controller_instance.sh|cmd
- For details see JS7 - Controller - Command Line Operation
- for an Agent instance:
./bin/agent_<port>.sh|cmd
- For details see JS7 - Agent Command Line Operation
Standard Arguments
The following arguments are used independently from an HTTP or HTTPS connection to JOC Cockpit:
Arguments for use with JOC Cockpit HTTPS Connections
The following arguments are used in addition to standard arguments in case that JOC Cockpit is set up for HTTPS connections:
Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication
The following arguments are used in addition to HTTPS connection arguments in case that JOC Cockpit is setup for JOC Cockpit - HTTPS Mutual Authentication.
Examples
Standard Examples
Example for use with the Controller/Agent Instance Start Script and default values
# use with a Controller instance ./bin/controller_instance.sh cert --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446 # use with an Agent instance ./bin/agent_<port>.sh cert --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446
Explanation:
- the
cert
argument for the Instance Start Script to build the Java classpath and to start the Java executable. - The
--token
argument specifies the one-time token to connect to JOC Cockpit. - The
--joc-uri
argument specifies the URL for JOC Cockpit. - If no additional arguments are used then the Command Line Client determines default values for the Keystore and Truststore from the instances'
./config/private/private.conf
configuration, including defaults for the DN and for the SAN of the certificate.
Example for use with the Controller/Agent Instance Start Script to update relevant DN entries
# use with a Controller instance ./bin/controller_instance.sh cert --dn-only --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446 # use with an Agent instance ./bin/agent_<port>.sh cert --dn-only --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446
Explanation:
- With the
--dn-only
argument only relevant Distinguished Names (DNs) will be updated to the./config/private/private.conf
configuration file.
Advanced Examples
Example for use with an HTTP Connection to JOC Cockpit
Explanation:
- tbd
Example for use with an HTTPS Connection to JOC Cockpit and Mutual Authentication from a Client Truststore
Explanation:
- tbd
Example for use with an HTTPS Connection to JOC Cockpit and Mutual Authentication from a Client Key File
Explanation:
- tbd