...

• Service Type: CERTIFICATE
  • Management of user accounts is performed by the Certificate Authority (CA). Instead of a password the user holds the private keyPrivate Key and Certificate.
  • The assignment of roles to user accounts is performed by the JOC Cockpit.
  • The JOC Cockpit stores user accounts and role assignments: in the JS7 - Database.
  • The JOC Cockpit does not know the private key Private Key of user accounts. JOC Cockpit knows the user account's public key Certificate that is used to verify authentication requests.

...

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

## enable use of client authentication certificates
jetty.sslContext.needClientAuth=false
jetty.sslContext.wantClientAuth=true
jetty.sslContext.endpointIdentificationAlgorithm=

...

Mutual authentication is based on X.509 compliant certificates. SelfPrivate CA-signed certificates Certificates and Public CA-signed certificates Certificates can be used, for details see JS7 - How to create X.509 SSL TLS Certificates.

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

• Self-signed Certificates
  • JOC Cockpit holds the client's certificate in its truststore. 
  • Each client's individual certificate is required to be in place.
• CA signed Certificates
  • JOC Cockpit holds the CA certificateCertificate, i.e. the Root CA Certificate/Intermediate CA Certificate(s), in its truststore.
  • 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 modification of the Jetty truststore when adding/removing clients.

Client Configuration

Certificate Management

SelfPrivate CA-signed certificates and certificates signed by trusted root certification authorities (CA) can be usedCertificates and Public CA-signed Certificates can be used:

• Private CA-signed Certificates are issued by users who operate their own Private Certificate Authority (CA).
• Public CA-signed Certificates are issued by a trusted Certificate Authority (CA) that validates the domain owner. They are not created by users but are purchased from the trusted CA and are not in scople of this article.

For use with selfPrivate CA-signed certificates Certificates the Root CA Certificate has to be added to the client's certificate store. Certificates from trusted Root Public CAs are frequently available from a client's keystore.

Certificate Store

The client holds its private key Private Key and certificate Certificate in its keystore. 

• The private key 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 that is signed by a Private CA or Public CA.
• For CA-signed certificates Certificates the client's certificate store includes the certificate chain, i.e. client certificate and Root CA Certificate/Intermediate CA Certificate(s) that have been used when signing the client's certificate.
• Frequently private key Private Key and certificateCertificate(s) are stored in a PKCS12 keystore that comes with a .pfx or .p12 file extension. However, other Other file formats for private key Private Key and certificateCertificate(s) are can be used.
• The clients' keystore 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): support for use of an individual certificate store that is available with the browser, see Options -> Privacy & Security -> Certificates.
    • Chrome, Vivaldi, Edge (Windows): support for use of the Windows Certificate Store
    • Chrome, Vivaldi (Linux): support for use of an individual certificate store that is available with the browser, see Options -> Privacy
    • Chrome, Safari (Mac OS): support for use of the Mac OS Certificate Store
  • REST Clients
    • JS7 PowerShell Module (Connect-JS7): Windows, Linux, Mac OS: support for use of a PKCS12 keystore (.p12); Windows: support for 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.

...

• Jetty will verify the Client Authentication Certificate and check if this was signed by a CA using the Root CA Certificate that is available with the Jetty truststore.
• During login the user does not have to specify the account to be used. Instead, the Common Name (CN) entry of the Client Authentication Certificate's subject specifies the account used for login with JOC Cockpit. Consider that an exact match of the CN is required: 
  
  • Assume a user account: apmacwin
  • The certificate subject could look like this:
    
    

Logging

• Log Files
  • See JS7 - Log Files and Locations
• Standard Log Files
  • Identity Services log output to the JETTY_BASE/logs/joc.log file. This includes reporting success or failure of authentication.
  • Successful and failed authentication attempts including the user accounts involved are logged to the JETTY_BASE/logs/audit.log file.
• Debug Log Files
  • For problem analysis during the setup of an Identity Service, increase the log level as explained in the JS7 - Log Levels and Debug Options article.
  • The JETTY_BASE/logs/joc-debug.log file includes general debug output of JOC Cockpit.
  • The JETTY_BASE/logs/authentication-debug.log file includes debug output related to authentication and authorization.
  • The JETTY_BASE/logs/jetty.log file includes debug output of attempts to establish SSL connections.