Page History

...

Introduction

• The connection of from the user's browser and or any REST client to the JOC Cockpit can be secured by HTTPS. This includes that a client validates the JOC Cockpit SSL certificate for server authentication.
• In addition the JOC Cockpit can be configured for mutual authentication, requiring in addition the client to present a certificate that is validated by the JOC Cockpit.
• This article describes the steps required to set up secure JOC Cockpit for two-factor authentication including SSL mutual authentication and password authentication. For login to JOC Cockpit a client, i.e. a user browser or REST client,
  • is required to hold a certificate stored with the client's device that is validated by JOC Cockpit and
  • is required to specify a password.

Prerequisites

• JOC Cockpit is set up to use HTTPS Communication.

JOC Cockpit Configuration

Jetty Configuration

JETTY_BASE is Jetty's base directory which is specified during the JOC Cockpit installation:

...

• Line 4: this setting looks weird, however, it is required due to a bug in Jetty 9.4, see https://github.com/eclipse/jetty.project/issues/3466. With later releases of Jetty that fix this bug the setting will not be required.

JOC Cockpit Certificate Management

Mutual authentication is based on X509 X.509 compliant certificates. Self-signed certificates and CA signed certificates can be used.

...

JOC Cockpit hold a certificate that allows validation of the clients' certificate in its truststoretrust store. The location of the Jetty truststore trust store is specified with the JETTY_BASE/start.ini configuration file.

• Self-signed Certificates
  • JOC Cockpit holds the client's certificate in its truststoretrust store. 
  • Each client's individual certificate is required to be in place.
• CA signed Certificates
  • JOC Cockpit holds the CA certificate, i.e. the root certificate/intermediate certificate(s), in its truststoretrust store.
  • Connections from any clients that use a certificate signed by the CA will be accepted.
  • This approach is more flexible as it does not require to modify the Jetty truststore trust store when adding/removing clients.

Client Configuration

Client Certificate Management

Self-signed certificates and certificates signed by trusted root certification authorities can be used.

For use with self-signed certificates the root certificate has to be added to the Client's certificate store. Certificates from trusted root certification authorities frequently are available from a Client's key store.

Certificate Store

The client holds its private key and certificate in its keystorekey store. 

• The private key is created by the client when generating a key pair for a self-signed certificate and respectively when creating a certificate signing request (CSR) for its CA.
• For CA signed certificates the client's certificate store includes the certificate chain, i.e. client certificate and root certificate/intermediate certificate(s) that have been used to sign the client's certificate.
• Frequently private key and certificate(s) are stored in a PKCS12 keystore key store that comes with a .pfx or .p12 file extension. However, other file formats for private key and certificate(s) are available.
• The clients' keystore key store has to be imported into the client's certificate store. The location of the certificate store depends on the client application that is used to access JOC Cockpit:
  • Browser Clients
    • FireFox (any platform):
  • The Internet Explorer, Edge and Chrome browsers are reported to use the Windows certificate store.
  • The FireFox browser makes use of its own certificate store.
  • •  supports use of an individual certificate store that is available with the browser, see Options -> Privacy & Security -> Certificates.
    • Chrome, Vivaldi, Edge (Windows): supports use of the Windows Certificate Store
    • Chrome, Vivaldi (Linux): supports use of an individual certificate store that is available with the browser, see Options -> Privacy
    • Chrome, Safari (Mac OS): supports use of the Mac OS Certificate Store
  • REST Clients
    • JS7 PowerShell Module (Connect-JS7): Windows, Linux, Mac OS: supports use of a Key Store (.p12); Windows: supports use of the Windows Certificate Store
    • JobScheduler PowerShell Module (Connect-JobScheduler): Windows, Linux, Mac OS: supports use of a Key Store (.p12); Windows: supports use of the Windows Certificate Store
    • Other REST Clients: REST clients implemented with programming languages or scripting languages follow individual approaches to manage a certificate store
    .

The JobScheduler PowerShell Modules for JobScheduler 1.x and for JobScheduler 2 (JS7) both support to specify client certificates from keystores and from the operating system certificate store.

• • • .

Certificate Encryption Algorithms

X.509 Certificates with RSA or ECDSA encryption algorithms can be used.

Certificate Verification

When connecting from a Client, e.g. a browser, to the JOC Cockpit server then JOC Cockpit will challenge the Client to present its Client Authentication Certificate.

• JOC Cockpit will verify the Client Authentication Certificate and check if this was signed by CA that holds the Root Certificate that is available with the JOC Cockpit trust store.
• During login the user has to specify the account that has to match the Common Name (CN) entry of the Client Authentication Certificate's subject. Please consider that an exact match is required: 
  
  • Assume a user account: apmacwin
  • The certificate subject could look like this:
    
    Image Added
• JobScheduler 1.x: PowerShell CLI 1.2 - Cmdlets - Connect-JobScheduler
• JobScheduler 2.x: PowerShell CLI 2.0 - Cmdlets - Connect-JS7