Client Certificate Authentication Improvements in Payara Server July and September 2021 Releases

SSL certificates are used for several features within Payara Server. You can configure your custom certificate for the TLS based connections the Payara Server is serving when using a custom domain name. And those certificates can be used for authentication purposes to identify the caller, mainly in a machine to machine communication.

With the July and September 2021 Payara Server releases, we have implemented two new features to improve the usage of these custom SSL certificates.

(Read more about SSL certificates in the Payara Server documentation.)

Payara Server TrustStore

The TrustStore contains all root certificates of the Certificate Authorities so the client connection from within your application to other secured endpoints can be established. This same TrustStore also contains the default self-signed certificate so Payara Server can accept secure connections from clients.

This self-signed certificate must be replaced with a certificate you acquired from a Certificate Authority, and is described in the Securing Payara Server with Custom Certificate article.

The TrustStore must also contain the accepted Client Certificates if your application is configured to use the Certificate Realm.

With this release, we have introduced an additional System Property so multiple TrustStores can be defined. This way, your configuration is separated from the Payara Server one, which helps when you install and configure an upgrade.

System Property

The new System Property for an additional TrustStore is fish.payara.ssl.additionalTrustStores .We also introduced a property to define additional KeyStores fish.payara.ssl.additionalKeyStores.

You can specify these properties through the asadmin CLI:

./asadmin create-jvm-options "-Dfish.payara.ssl.additionalTrustStores=/path/to/truststore.jks\:/path2/to/truststore2.jks"

These properties can also be specified through the Admin Console as a JVM Option.

The password on these TrustStores and KeyStores must be the same as the password on Payara Server TrustStore so the content can be read.

When you install a new version of Payara Server, you can easily keep your custom configuration within the TrustStore and KeyStore, as it is now in a separate file that is not part of the Payara Server installation itself. After installing, you only need to add the System Property and do not need to import all the certificates in the Payara Server TrustStore anymore.

Client Certificate Authentication

As already mentioned, the TrustStore is also used when you configure your application for Client Certificate Authentication.

During the setup of the SSL connection, the server will request a Client Certificate from the client so that the connection is secured but also so the server can guarantee that the client is allowed to make the connection.

Currently, when the received Client Certificate is found within the Payara Server TrustStore, it is accepted and based on the role mapping, we can grant the client access to the application.

With the September 2021 Payara Server release, we have implemented an SPI so developers can perform additional checks on the Client Certificate. When the Certificate issuer supports revocation of the certificates, the status can be retrieved through the Online Certificate Status Protocol (OCSP). This SPI allows you to implement any kind of additional check you like.  The interface you need to implement is:

public interface ClientCertificateValidator {

    boolean isValid(Subject subject, X500Principal principal, X509Certificate certificate);
}

As parameters, you have the Subject, The Principal from the certificate, and the entire certificate itself available to work with. Implementations of this interface are loaded through the serviceloader mechanism. Don't forget to include a file called fish.payara.security.api.ClientCertificateValidator containing the fully qualified class name of your class into the /META-INF/services directory.

Be aware that your code will be executed within the SSL connection setup phase and should be as efficient as possible so that the impact on the performance of your application is minimal.

Custom SSL Certificate Improvements

The July and September 2021 Payara Server releases contain a few improvements if you are working with Custom SSL certificates.  Using the new JVM property, you can define additional TrustStores and KeyStores so that it becomes easier when you upgrade your Payara Server environment. And with the ClientCertificateValidator you can implement additional checks like the OCSP validation when you are using the Client Certificate Authentication option of Payara Server.