Client Certificate Realm Configuration in Payara Server

A realm is the security policy domain within an application server. It defines how the authentication and authorization for your application is performed. Most of the time, your application is used by a person that can provide username and passwords as credentials (directly or indirectly through providers like an OpenId Connect provider) but some use cases exist where another process needs to use your endpoints.

The usage of Client Certificates is common in this scenario and allows you to uniquely identify the process that connects to your application.

The Client Certificate realm is mandatory as it is a part of the Jakarta EE specification. We have added some additional functionality to the Client Certificate realm when used with Payara Server, which we will provide an overview of how to use the additional functionality and what additional features are available to you:

How Does it Work?

How does a Client Certificate work? When you configure Payara Server it asks the client for a Client Certificate.  This certificate would typically contain pertinent information like a digital signature, expiration date, name of client, name of  Certificate Authority certificate, serial number, and possibly more, all structured using the X.509 standard.

When Payara Server receives the Client Certificate, it verifies if it is a certificate that is allowed access to the application.  This is the authentication step, just as it would verify the username and password credentials. Once the certificate is accepted, the role(s) are determined so that authorization within the application can be executed.

The basic feature within Payara Server requires that the Client Certificate is loaded into a Payara Keystore, and the groups are defined based on the full principal name of the Certificate. In this blog, we describe how you can set up the realm and the additional features we have implemented to make the authentication and authorization based on Client Certificates easier.

Realm Setup

There are two options for activating the Client Certificate Realm within Payara Server. The first option is to define the <login-config> tag within the web.xml file. The second option is the @CertificateIdentityStoreDefinition annotation that is based on the Jakarta EE Security API but is not yet available within the Jakarta EE specification.

The following config within the web.xml file is enough to activate the client certificates realm for your application.

<login-config>
   <auth-method>CLIENT-CERT</auth-method>
   <realm-name>certificate</realm-name>
</login-config>

Of course, you also need to define which endpoints are secured and what role is required to access them. The following config requires a valid authentication and the role myRole to access all endpoints within the /secure area.

<security-constraint>
   <web-resource-collection>
      <web-resource-name>secureAccess</web-resource-name>
      <url-pattern>/secure/*</url-pattern>
   </web-resource-collection>
   <auth-constraint>
      <role-name>myRole</role-name>
   </auth-constraint>
</security-constraint>

Another option is to use the annotations that we have created to have the Certificate Realm integration within the Jakarta EE Security API framework.

@CertificateAuthenticationMechanismDefinition
@CertificateIdentityStoreDefinition("certificate-realm")

Important here is that the name of the store should not be 'certificate' as that clashes with the default of Payara Server used when configured through the web.xml file and that also the appropriate Authentication mechanism is declared.

Additional Authentication Features

The Client Certificates that need to be accepted must be stored within a Keystore that can be accessed by the Payara Server.  Storing it in the Keystore is similar to validating the username and password credentials. The entry is accepted and the user, the client providing the Client Certificate, is allowed to access the application.

With the July 2021 release, Payara Server can handle now multiple Keystores and not only the Keystore of Payara Server itself. You can now put the Client Certificate in a Keystore outside of Payara Server which makes the upgrades easier as you do not need to reimport the certificate after an upgrade.

In the September Release of 2021, we added an SPI that can be used to perform additional checks on the Client Certificate within the authentication phase. You can implement some standards with that like the Online Certificate Status Protocol to determine if the Certificate is still valid, or you can implement your additional checks to determine if you still want to accept it.

The SPI itself can be used to activate the check to verify if the Certificate is not yet expired, available since the October release.

Additional Authorization Features

Within Jakarta EE, permissions are used to determine if a certain user has the right to execute a certain method or access an endpoint.  The requirements can be specified using the web.xml <security-constraint> element as we have seen in the setup section earlier. You can also define the required role by using the:

@RolesAllowed("myRole")

on the definition of the endpoint like the Servlet class or the JAX-RS resource method.

Since the Client Certificate has no notion of roles or groups within the structure itself, we need to define them within our environment using the payara-web.xml file.

<security-role-mapping>
   <role-name>myRole</role-name>
   <group-name>myGroup</group-name>
   <principal-name>CN=Rudy De Busscher,EMAILADDRESS=rudy.debusscher@some.org,C=BE</principal-name>
</security-role-mapping>

This defines the group and also the role (there is also the group to role conversion that can be used in this case) for the principal name defined within the Client Certificate.

However, the principal name must exactly match the value that is defined within the Client Certificate and can sometimes be tricky to know.  Payara helps you with this task as we have an asadmin command available that shows you this value and which you can copy and paste into the configuration file.

./asadmin print-certificate <certificate-file>

The above prints out the various parts of the certificate including the subject which you can use for the principal-name element in the mapping of payara-web.xml file.

But we have also two options to make the mapping easier than using the long and complicated subject name of the certificate.

You can use the common name defined in the Certificate as the principal name within the mapping. For more information on how you can configure this, look at our documentation.

Another option you have is to define the OU part, or any other part as you can configure which part of the Subject name, as the group, and determine the permissions based on this.

Conclusion

The Client Certificate Authentication option of Jakarta EE is a good option if you want to secure access from a process to your application. The certificate replaces the user name and password credentials and to be accepted, it must be placed within a Keystore that can be accessed by the Payara Server.

Besides the standard requirements, Payara has implemented several features to make it easier to work with those Client Certificates. There is an SPI to perform additional validations on the certificate before it is accepted. And the groups and roles can be defined on the principal name, but also on parts of it so that you have greater flexibility.

We also created annotations based on the Jakarta EE Security API to allow easier integration with custom requirements. This possibility might be included also in the specification itself with Jakarta EE 10 or later.