Chapter 5. Certificate-Based Login Modules

5.1. Certificate Login Module

Short name: Certificate

Full name: org.jboss.security.auth.spi.BaseCertLoginModule

Parent: AbstractServer Login Module

Certificate login module authenticates users based on X509 certificates. A typical use case for this login module is CLIENT-CERT authentication in the web tier. This login module only performs authentication and must be combined with another login module capable of acquiring authorization roles to completely define access to a secured web or EJB components. Two subclasses of this login module, CertRoles Login Module and DatabaseCert Login Module extend the behavior to obtain the authorization roles from either a properties file or database.

Table 5.1. Certificate Login Module Options

OptionTypeDefaultDescription

securityDomain

String

other

Name of the security domain that has the JSSE configuration for the truststore holding the trusted certificates.

verifier

class

none

The class name of the org.jboss.security.auth.certs.X509CertificateVerifier to use for verification of the login certificate.

5.2. CertificateRoles Login Module

Short name: CertificateRoles

Full name: org.jboss.security.auth.spi.CertRolesLoginModule

Parent: Certificate Login Module

The CertificateRoles login module adds role mapping capabilities from a properties file using the following options:

Table 5.2. CertificateRoles Login Module Options

OptionTypeDefaultDescription

rolesProperties

String

roles.properties

The name of the resource or file containing the roles to assign to each user. The role properties file must be in the format username=role1,role2 where the user name is the DN of the certificate, escaping any equals and space characters. The following example is in the correct format: CN\=unit-tests-client,\ OU\=Red\ Hat\ Inc.,\ O\=Red\ Hat\ Inc.,\ ST\=North\ Carolina,\ C\=US

defaultRolesProperties

String

defaultRoles.properties

Name of the resource or file to fall back to if the rolesProperties file cannot be found.

roleGroupSeparator

A single character.

. (a single period)

Which character to use as the role group separator in the rolesProperties file.

5.3. DatabaseCertificate Login Module

Short name: DatabaseCertificate

Full name: org.jboss.security.auth.spi.DatabaseCertLoginModule

Parent: Certificate Login Module

The DatabaseCertificate login module adds mapping capabilities from a database table through these additional options:

Table 5.3. DatabaseCertificate Login Module Options

OptionTypeDefaultDescription

dsJndiName

A JNDI resource

java:/DefaultDS

The name of the JNDI resource storing the authentication information.

rolesQuery

prepared SQL statement

select Role,RoleGroup from Roles where PrincipalID=?

SQL prepared statement to be executed in order to map roles. It should be an equivalent to the query 'select Role, RoleGroup from Roles where PrincipalID=?', where Role is the role name and the RoleGroup column value should always be either Roles with a capital R or CallerPrincipal.

suspendResume

true or false

true

Whether any existing JTA transaction should be suspended during database operations.

transactionManagerJndiName

JNDI Resource

java:/TransactionManager

The JNDI name of the transaction manager used by the login module.