Client Certificate Custom Validations

By default, the Payara Server runtime checks only if the submitted Client Certificate is present in the trust store and that it hasn’t expired already. If this conditions are met, it is accepted without any additional checks.

Custom Client Certificate Validation allows you to perform extra checks in addition to checking for the presence of the certificate in the trust store.

You can perform a check on the validity date, and use the Online Certificate Status Protocol (OCSP) to validate the certificate when it has a Certificate Revocation List entry (CRL), or lookup the DN name in a database for example, and determine based on this information if the certificate is still accepted.

Creating a Custom Validator

When you want to implement custom validation, implement the fish.payara.security.client.ClientCertificateValidator interface and define your class through the ServiceLoader mechanism.

To have the ClientCertificateValidator interface available in your application, add the payara-api artifact to your application with the provided scope. When using maven, add the following snippet if not already defined.

<dependency>
    <groupId>fish.payara.api</groupId>
    <artifactId>payara-api</artifactId>
    <version>{currentVersion}</version>
    <scope>provided</scope>
</dependency>

Now that you have the interface available, you can implement it in your application.

public class MyCertificateValidator implements ClientCertificateValidator {

    @Override
    public boolean isValid(Subject subject, X500Principal principal, X509Certificate certificate) {
         //
         return ...
    }
}

The most important parameter here is the principal parameter which contains the user information contained in the Client Certificate presented in the request. The Certificate itself is in the last parameter and in the case you like to have access already to the Subject for this validation, it is passed in as the first parameter.

When you return true as the method result, the processing of the request continues. In the case false is returned, a LoginException is thrown resulting in a status 401 for the request.

This class is loaded through the Java ServiceLoader mechanism. Make sure you have the following file. META-INF/services/fish.payara.security.client.ClientCertificateValidator containing the fully qualified name of your implementation.

com.company.certificate.MyCertificateValidator
You can @Inject CDI and EJB beans in your validator implementation, however since the validator itself is not a Jakarta EE bean, @PostConstruct and @PreDestroy-annotated methods will not be called on the validator instance.

Certificate Expiration Validation

By default, certificate expiration validation is enabled. This validation checks if the certificates in the trust store haven’t expired yet. If the client certificate has expired or is not valid yet, a warning message will be printed in the server logs.

Using the Asadmin CLI

You can use the following asadmin command to set the value of the property through:

asadmin> set configs.config.${YOUR_INSTANCE_CONFIG}.security-service.auth-realm.certificate.property.certificate-validation=[true/false]

Using the Admin Console

This feature can be configured on the default certificate realm as follows on the Admin Console:

  1. Navigate to the applicable configuration page for your use (e.g. server-config) under the Configurations option in the side menu

  2. Head to Security → Realms and select the certificate realm

  3. Set the property certificate-validation value to [true/false]

Certificate Expiration Validation Setting

After setting the value of the property, make sure that you restart the server instance for the changes to take effect.