Menu Close

Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Chapter 6. Configuring a Security Domain to Use Certificate-Based Authentication

JBoss EAP provides you with the ability to use certificate-based authentication with security domains to secure web applications or EJBs.

Important

Before you can configure certificate-based authentication, you need to have Two-Way SSL/TLS for Applications enabled and configured, which requires X509 certificates configured for both the JBoss EAP instance as well as any clients accessing the web application or EJB secured by the security domain.

Once the certificates, truststores, and two-way SSL/TLS are configured, you then can proceed with configuring a security domain that uses certificate-based authentication, configuring an application to use that security domain, and configuring your client to use the client certificate.

6.1. Creating a Security Domain with Certificate-Based Authentication

To create a security domain that uses certificate-based authentication, you need to specify a truststore as well as a Certificate login module or one of its subclasses.

The truststore must contain any trusted client certificates used for authentication, or it must contain the certificate of the certificate authority used to sign the client’s certificate. The login module is used to authenticate the certificate presented by the client using the configured truststore. The security domain as a whole also must provide a way to map a role to the principal once it is authenticated. The Certificate login module itself will not map any role information to the principal, but it may be combined with another login module to do so. Alternatively, two subclasses of the Certificate login module, CertificateRoles and DatabaseCertificate, do provide a way to map roles to a principal after it is authenticated. The below example shows how to configure a security domain with certificate-based authentication using the CertificateRoles login module.

Warning

When performing authentication, the security domain will use the same certificate presented by the client when establishing two-way SSL/TLS. As a result, the client must use the same certificate for BOTH two-way SSL/TLS and the certificate-based authentication with the application or EJB.

Example Security Domain with Certificate-Based Authentication

/subsystem=security/security-domain=cert-roles-domain:add

/subsystem=security/security-domain=cert-roles-domain/jsse=classic:add(truststore={password=secret, url="/path/to/server.truststore.jks"}, keystore={password=secret, url="/path/to/server.keystore.jks"}, client-auth=true)

/subsystem=security/security-domain=cert-roles-domain/authentication=classic:add

/subsystem=security/security-domain=cert-roles-domain/authentication=classic/login-module=CertificateRoles:add(code=CertificateRoles, flag=required, module-options=[ securityDomain="cert-roles-domain", rolesProperties="${jboss.server.config.dir}/cert-roles.properties",password-stacking="useFirstPass", verifier="org.jboss.security.auth.certs.AnyCertVerifier"])

Note

The above example uses the CertificateRoles login module to handle authentication and map roles to authenticated principals. It does so by referencing a properties file using the rolesProperties attribute. This file lists usernames and roles using the following format:

user1=roleA
user2=roleB,roleC
user3=

Since usernames are presented as the DN from the provided certificate, for example CN=valid-client, OU=JBoss, O=Red Hat, L=Raleigh, ST=NC, C=US, you have to escape special characters such as = and spaces when using a properties file:

Example Roles Properties File

CN\=valid-client,\ OU\=JBoss,\ O\=Red\ Hat,\ L\=Raleigh,\ ST\=NC,\ C\=US=Admin

To view, the DN of certificate:

$ keytool -printcert -file valid-client.crt
Owner: CN=valid-client, OU=JBoss, O=Red Hat, L=Raleigh, ST=NC, C=US
...

6.2. Configuring an Application to use a Security Domain with Certificate-Based Authentication

Similar to configuring an application to use a security domain with other forms of authentication, you need to configure both the jboss-web.xml and web.xml files appropriately.

For jboss-web.xml, you add a reference to the security domain you configured for certificate-based authentication.

Example jboss-web.xml

<jboss-web>
  <security-domain>cert-roles-domain</security-domain>
</jboss-web>

For the web.xml, set the <auth-method> attribute in <login-config> to CLIENT-CERT. You also need to have a <security-constraint> as well as <security-roles> defined as well.

Example web.xml

<web-app>
  <!-- URL for secured portion of application-->
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>secure</web-resource-name>
      <url-pattern>/secure/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>All</role-name>
    </auth-constraint>
  </security-constraint>

  <!-- Security roles referenced by this web application -->
  <security-role>
    <description>The role that is required to log in to the application</description>
    <role-name>All</role-name>
  </security-role>

  <login-config>
    <auth-method>CLIENT-CERT</auth-method>
    <realm-name>cert-roles-domain</realm-name>
  </login-config>
</web-app>

6.3. Configuring the Client

For a client to authenticate against an application secured with certificate-based authentication, the client needs access to a client certificate that is contained in the JBoss EAP instance’s truststore. For example, if accessing the application using a browser, the client will need to import the trusted certificate into the browser’s truststore.