Red Hat Training
A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform
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
| Option | Type | Default | Description |
|---|---|---|---|
| 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>
