Chapter 5. Configuring a Security Domain to use a Database

Similar to LDAP, security domains can be configured to use a database for authentication and authorization by using a login module.

5.1. Database Login Module

The Database login module is a Java Database Connectivity-based (JDBC) login module that supports authentication and role mapping. This login module is used if username, password and role information are stored in a relational database.

This works by providing a reference to logical tables containing Principals and Roles in the expected format. For example:

Table Principals(PrincipalID text, Password text)
Table Roles(PrincipalID text, Role text, RoleGroup text)

The Principals table associates the user PrincipalID with the valid password and the Roles table associates the user PrincipalID with its role sets. The roles used for user permissions must be contained in rows with a RoleGroup column value of Roles.

The tables are logical in that users can specify the SQL query that the login module uses. The only requirement is that the java.sql.ResultSet has the same logical structure as the Principals and Roles tables described previously. The actual names of the tables and columns are not relevant as the results are accessed based on the column index.

To clarify this notion, consider a database with two tables, Principals and Roles, as already declared. The following statements populate the tables with the following data:

  • PrincipalID java with a Password of echoman in the Principals table
  • PrincipalID java with a role named Echo in the RolesRoleGroup in the Roles table
  • PrincipalID java with a role named caller-java in the CallerPrincipalRoleGroup in the Roles table

Table 5.1. Complete Database Login Module Options

OptionTypeDefaultDescription

digestCallback

A fully-qualified classname

none

The class name of the DigestCallback implementation that includes pre/post digest content like salts for hashing the input password. Only used if hashAlgorithm has been specified.

dsJndiName

A JNDI resource

java:/DefaultDS

The name of the JNDI resource storing the authentication information. This option is required.

hashAlgorithm

String

Use plain passwords

The message digest algorithm used to hash passwords. Supported algorithms depend on the Java Security Provider, but the following are supported: MD5, SHA-1, and SHA-256.

hashCharset

String

The platform’s default encoding

The name of the charset/encoding to use when converting the password String to a byte array. This includes all supported Java charset names.

hashEncoding

String

Base64

The string encoding format to use.

ignorePasswordCase

boolean

false

A flag indicating if the password comparison should ignore case.

inputValidator

A fully-qualified classname

none

The instance of the InputValidator implementation used to validate the username and password supplied by the client.

principalsQuery

prepared SQL statement

select Password from Principals where PrincipalID=?

The prepared SQL query to obtain the information about the principal.

rolesQuery

prepared SQL statement

none

The prepared SQL query to obtain the information about the roles. It should be equivalent to 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.

storeDigestCallback

A fully-qualified classname

none

The class name of the DigestCallback implementation that includes pre/post digest content like salts for hashing the store/expected password. Only used if hashStorePassword or hashUserPassword is true and hashAlgorithm has been specified.

suspendResume

boolean

true

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

throwValidatorError

boolean

false

A flag that indicates whether validation errors should be exposed to clients or not

transactionManagerJndiName

JNDI Resource

java:/TransactionManager

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

5.1.1. Configuring a Security Domain to use the Database Login Module

Before configuring a security domain to use the Database login module, a datasource must be properly configured. For more information on creating and configure datasources in JBoss EAP 6 please see the Datasource Management section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide.

Once a datasource has been properly configured, a security domain may be configured to use the Database login module. The below example assumes a datasource named MyDatabaseDS has been created and properly configured with a database that is constructed with the following:

CREATE TABLE Users(username VARCHAR(64) PRIMARY KEY, passwd VARCHAR(64))
CREATE TABLE UserRoles(username VARCHAR(64), role VARCHAR(32))

CLI Commands for Adding the Database Login Module

/subsystem=security/security-domain=testDB:add

/subsystem=security/security-domain=testDB/authentication=classic:add
/subsystem=security/security-domain=testDB/authentication=classic/login-module=Database:add( \
  code=Database, \
  flag=required, \
  module-options=[ \
    ("dsJndiName"=>"java:/MyDatabaseDS"), \
    ("principalsQuery"=>"select passwd from Users where username=?"), \
    ("rolesQuery"=>"select role, 'Roles' from UserRoles where username=?") \
  ])
reload

Resulting XML

<security-domain name="testDB">
  <authentication>
    <login-module code="Database" flag="required">
      <module-option name="dsJndiName" value="java:/MyDatabaseDS"/>
      <module-option name="principalsQuery" value="select passwd from Users where username=?"/>
      <module-option name="rolesQuery" value="select role, 'Roles' from UserRoles where username=?"/>
    </login-module>
  </authentication>
</security-domain>