Configure Using Distinguished Name Parts for Groups

Since Payara Server 5.194

Since Payara 5.194 you can also configure mapping of client certificate’s distinguished name to groups, used for mapping to roles, used for authorization.

This feature can be configured by the property named dn-parts-used-for-groups of any security realm of type com.sun.enterprise.security.auth.realm.certificate.CertificateRealm. This property can contain a comma separated list of identifiers of DN parts, ie. EMAILADDRESS,DC,OU, and it is empty by default. The default empty value means that only content of assign-groups property value will be used as the list of assigned groups.

If both properties are set, a principal who passed the certificate validation will have all groups from both assign-groups value and those mapped from the certificate DN as configured here.

For mapping are usable only DN parts from the following table, other will be ignored:

Table 1. Supported OIDs

DN Part Id

OID Name

Object ID

CN

Common Name

2.5.4.3

SURNAME

Surname

2.5.4.4

SERIALNUMBER

Serial Number of the certificate

2.5.4.5

C

Country

2.5.4.6

L

Locality

2.5.4.7

ST

State

2.5.4.8

STREET

Street

2.5.4.9

O

Organisation

2.5.4.10

OU

Organisation Unit

2.5.4.11

T

Title

2.5.4.12

GIVENNAME

Given Name

2.5.4.42

INITIALS

Initials

2.5.4.43

GENERATION

Generation

2.5.4.44

DNQUALIFIER

DN Qualifier

2.5.4.46

UID

User ID

0.9.2342.19200300.100.1.1

DC

Domain Component

0.9.2342.19200300.100.1.25

EMAILADDRESS

E-Mail address

1.2.840.113549.1.9.1

IP

IP Address

1.3.6.1.4.1.42.2.11.2.1

Configuration of the Payara Server

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 dn-parts-used-for-groups and set the Value to a comma separated list of OID names.

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.dn-parts-used-for-groups=EMAILADDRESS,DC,OU
After setting the value of the property, make sure that you restart the server instance for the changes to take effect.

Using DN parts as Groups in Applications

When we configured realm to use parts of distinguished name for groups, and maybe even using CN as principal name, we can also map these groups to roles.

The mapping is done in standard way by other server components, but let’s summarize some set of rules:

  • principal receives principal name as configured (whole DN or only CN part)

  • principal receives all groups from realm’s assign-groups list

  • principal receives all groups from certificate’s DN parts listed in dn-parts-used-for-groups realm property (limited to those listed in table)

  • server allows the principal to access the application

  • client receives all roles from application’s security role mapping, where at least one of his principal names or groups matches their respective element.

  • roles are used for authorization to access application resources

For example, if user authorization roles were mapped like this in the payara-web.xml deployment descriptor and we enabled using CN as a principal name and set the dn-parts-used-for-groups to OU:

<?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>role1</role-name>
    <principal-name>C=UK, S=lak, L=zak, OU=unitA, CN=foo1</principal-name>
    <principal-name>C=UK, S=lak, L=zak, OU=unitA, CN=foo2</principal-name>
    <principal-name>C=UK, S=lak, L=zak, OU=unitC, CN=foo4</principal-name>
    <principal-name>C=UK, S=lak, L=zak, OU=unitD, CN=foo-director</principal-name>
  </security-role-mapping>
  <security-role-mapping>
    <role-name>role2</role-name>
    <principal-name>C=UK, S=lak, L=zak, OU=unitB, CN=foo3</principal-name>
    <principal-name>C=UK, S=lak, L=zak, OU=unitD, CN=foo-director</principal-name>
  </security-role-mapping>
</payara-web-app>

Then the role mapping can be based on organizational unit in this case. But you can still use the principal name too:

<?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>role1</role-name>
    <group-name>unitA</group-name>
    <group-name>unitC</group-name>
    <group-name>unitD</group-name>
  </security-role-mapping>
  <security-role-mapping>
    <role-name>role2</role-name>
    <group-name>unitB</group-name>
    <principal-name>foo-director</principal-name>
  </security-role-mapping>
</payara-web-app>

You have to use the dn-parts-used-for-groups property wisely - the set of values must be predictable to be useful. If you decided to use more ids to filter out group names from a distinguished name, it can cause some group name collisions, ie you can have a state UK and also organisational unit UK, then principal would have a single group UK. All parsed groups are equal.

The role mapping then works in the same way. It does not matter if it was mapped via principal name or any group name. If any rule matched, the principal has the role.