Chapter 6. Configuring a Security Domain to Use 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.

/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"])

user1=roleA
user2=roleB,roleC
user3=

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

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

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.

<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.

<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>

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.