Configure the Principal Name on Certificate Realms

Since Payara Server 5.192

Payara Server includes a feature that supports using exclusively the use of the Common-Name (CN) from a client certificate for authentication on a secure web application as the subject of any authenticated request.

A new property named common-name-as-principal-name can be used with any security realm of type com.sun.enterprise.security.auth.realm.certificate.CertificateRealm in order to control this feature.

The common-name-as-principal-name property is set to false by default if no configuration is provided.

Enabling Common Name As Principal Name

You can set this property by using either the Web administration console or the command line.

Using the Web Admin Console

This feature can be configured on the default certificate realm as follows on the Web administration 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. Click the Add Property button

  4. Set the property Name to be common-name-as-principal-name and set the Value to true

Common Name As Principal Name Setting

Using an asadmin command

You can also 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.common-name-as-principal-name=true
After setting the value of the property, make sure that you restart the server instance for the changes to take effect.

Using CN as Subject in Applications

With the feature enabled, users can be correctly authenticated when a valid certificate uses the common name instead of the full domain name. It is also possible to map users to roles in this manner.

For example, if user authorization roles were mapped like this in the payara-web.xml deployment descriptor:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE payara-web-app PUBLIC "-//Payara.fish//DTD Payara Server 4 Servlet 3.0//EN" "https://docs.payara.fish/schemas/payara-web-app_4.dtd">
<payara-web-app error-url="">
  <context-root>/health-services</context-root>
  <security-role-mapping>
    <role-name>gl</role-name>
    <principal-name>C=UK, S=lak, L=zak, O=kaz, CN=foo</principal-name>
  </security-role-mapping>
</payara-web-app>

Then the principal-name can be simplified by using only the CN part instead:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE payara-web-app PUBLIC "-//Payara.fish//DTD Payara Server 4 Servlet 3.0//EN" "https://docs.payara.fish/schemas/payara-web-app_4.dtd">
<payara-web-app error-url="">
  <context-root>/health-services</context-root>
  <security-role-mapping>
    <role-name>gl</role-name>
    <principal-name>foo</principal-name>
  </security-role-mapping>
</payara-web-app>