Client Certificate Custom Validations

By default, Payara checks only if the submitted Client Certificate is present in the trust store. If it is found, 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 Custom Validation

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.