Advanced Principal Name Configuration

Payara Server allows the use of the Common-Name (CN) attribute of a client certificate’s DN to be used as the full principal’s name when the certificated is authenticated in an application. This simplifies the authentication process, as the common name will replace the full name in the validation process of the certificate’s authentication.

To configure this behaviour, the common-name-as-principal-name property can be used in any security realm of type com.sun.enterprise.security.auth.realm.certificate.CertificateRealm.

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

Configuration

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. 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 the Asadmin CLI

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

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

Once this feature is enabled, users can be 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 directly.

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" "{payaraWebDtd}">
<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 common name like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE payara-web-app PUBLIC "-//Payara.fish//DTD Payara Server 4 Servlet 3.0//EN" "{payaraWebDtd}">
<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>