Introduction

Certificates can be used for mutual authentication:

• The client (Browser Client, REST Client) challenges the JOC Cockpit server to present its server authentication certificate that will be verified by the client.
• The JOC Cockpit server challenges the client to present its client authentication certificate that is verified by JOC Cockpit.

With JOC Cockpit being set up for mutual authentication the certificates can be used

• to enforce two-factor authentication with clients having to provide a certificate and a password,
• to allow single-factor authentication using a certificate instead of a password.

Authentication Strategies

Two-factor Authentication

This includes to require both account/password authentication and certificate based authentication.

Prerequisites

...

Consider that JOC Cockpit has to be set up for

JOC Cockpit - HTTPS Mutual Authentication - Two-factor Authentication

...

.

Configuration with Shiro

Single-factor

...

authentication boils down to use either account/password authentication or to allow certificate based authentication alternatively.

Find

Certificates for Authentication

Clients

Certificates are available with the Client's certificate store.

• 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: depends on implementation

Certificate Encryption Algorithms

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

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 Verification

...

JOC Cockpit makes use of Shiro for authentication management. Therefore changes have to be applied to the shiro.ini configuration file:

• On Windows systems the default location for the shiro.ini file is:
  • C:\ProgramData\sos-berlin.com\joc\resources\joc\shiro.ini
• On Unix systems the default location will be:
  • /home/[user]/sos-berlin.com/joc/resources/joc/shiro.ini

[users]
root = $shiro1$SHA-512$500000$W0oNBkZY9LRrRIGyc4z2Ug==$NcoU+ZFM9vsM0MeHJ3P5NJ0NdvJrK38qVnl7v7YG7p9o5ZJfMccugJsA9myJsTNx2BF5rbvA696UhTGdUtSnOg==,all
apmacwin = ,all

[main]
passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher
iniRealm.credentialsMatcher = $passwordMatcher

certRealm = com.sos.auth.shiro.SOSX509AuthorizingRealm
securityManager.realms = $iniRealm,$certRealm

# Session timeout in milliseconds
securityManager.sessionManager.globalSessionTimeout = 3600000

Explanations:

• The [users] section holds
  • accounts that are assigned a password hash and a number of roles,
  • accounts that are assigned a number of roles but not a password. If no password is specified then
    • the password can be specified by the user if an LDAP Configuration is in place with the [main] that will verify the password towards an LDAP Directory Server, e.g. Microsoft Active Directory®.
    • the password can be omitted if a certificate configuration is in place with the [main] section.
• The [main] section holds two lines for the certificate configuration:
  • certRealm = com.sos.auth.shiro.SOSX509AuthorizingRealm
securityManager.realms = $iniRealm,$certRealm
  • Consider the sequence of realms specified:
    • With the above configuration
      • first the account used for login will be checked for a matching entry with a password from the [users] section. This translates to the fact that for such accounts two-factor authentication is required as both a certificate and a password have to be specified.
      • then alternatively the account used for login will be checked if it provides a client authentication certificate. 
    • The sequence of realms can be modified and use of the $iniRealm can be dropped if no login with passwords should be enabled.