Product Knowledge Base

Space shortcuts

Page tree

Introduction

  • The connection from the user's browser 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 Configuration

Jetty Configuration

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

  • C:\ProgramData\sos-berlin.com\joc (default on Windows)
  • /home/<setup-user>/sos-berlin.com/joc (default on Linux)

Add the following entries to the JETTY_BASE/start.ini configuration file:

Add HTTPS mutual authentication to Jetty
## force use of client authentication certificates
jetty.sslContext.needClientAuth=true
jetty.sslContext.wantClientAuth=true
jetty.sslContext.endpointIdentificationAlgorithm=

Hints

  • Line 2: if needClientAuth is set to true then a Client Certificate is required. If this setting is false and the wantCientAuth setting is true then users have the option for user/password based authentication or certificate based authentication.
  • 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 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 trust store. The location of the Jetty trust store is specified with the JETTY_BASE/start.ini configuration file.

  • Self-signed Certificates
    • JOC Cockpit holds the client's certificate in its trust 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 trust 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 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 key 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 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' 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): 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.

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:



  • No labels