DatabaseServerLoginModule

A JDBC based login module that supports authentication and role mapping.

It is based on two logical tables:

• Principals(PrincipalID text, Password text)

• Roles(PrincipalID text, Role text, RoleGroup text)

LoginModule options:

• dsJndiName: The name of the DataSource of the database containing the Principals and Roles tables

• principalsQuery: The prepared statement query, equivalent to:

"select Password from Principals where PrincipalID=?"

• rolesQuery: The prepared statement query, equivalent to:

"select Role, RoleGroup from Roles where PrincipalID=?"

Note: Value of RoleGroup column always has to be Roles (with capital 'R'). This is specific to JBoss.

• unauthenticatedIdentity=name, Defines the principal name that should be assigned to requests that contain no authentication information. This can be used to allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and so can only access either unsecured EJBs or EJB methods that are associated with the unchecked permission constraint.

• password-stacking=useFirstPass, When password-stacking option is set, this module first looks for a shared username and password under the property names "javax.security.auth.login.name" and "javax.security.auth.login.password" respectively in the login module shared state Map. If found these are used as the principal name and password. If not found the principal name and password are set by this login module and stored under the property names "javax.security.auth.login.name" and "javax.security.auth.login.password" respectively.

• hashAlgorithm=string: The name of the java.security.MessageDigest algorithm to use to hash the password. There is no default so this option must be specified to enable hashing. When hashAlgorithm is specified, the clear text password obtained from the CallbackHandler is hashed before it is passed to UsernamePasswordLoginModule.validatePassword as the inputPassword argument. The expectedPassword as stored in the users.properties file must be comparably hashed.

• hashEncoding=base64|hex: The string format for the hashed pass and must be either "base64" or "hex". Base64 is the default.

• hashCharset=string: The encoding used to convert the clear text password to a byte array. The platform default encoding is the default.

• ignorePasswordCase=true|false: (3.2.3+) A boolean  flag indicating if the password comparison should ignore case. This can be useful for hashed password encoding where the case of the hashed password is not significant.

• principalClass: (3.2.4+) An option that specifies a Principal implementation class. This must support a ctor taking a String argument for the princpal name.

• suspendResume: (4.0.3+) A boolean flag that specifies that any existing JTA transaction be suspended during DB operations. The default is "true", i.e. query the database outside the thread's current transaction.

A sample Sun legacy format corresponding DatabaseServerLoginModule configuration would be:

testDB {
org.jboss.security.auth.spi.DatabaseServerLoginModule required
dsJndiName="java:/MyDatabaseDS"
principalsQuery="SELECT PASSWD FROM JMS_USERS WHERE USERID=?"
rolesQuery="SELECT ROLEID, 'Roles' FROM JMS_ROLES WHERE USERID=?"
;
};

The corresponding login-config.xml format entry is:

<application-policy name = "jbossmq">
  <authentication>
    <login-module code = "org.jboss.security.auth.spi.DatabaseServerLoginModule"
       flag = "required">
       <module-option name = "unauthenticatedIdentity">guest</module-option>
       <module-option name = "dsJndiName">java:/MyDatabaseDS</module-option>
       <module-option name = "principalsQuery">SELECT PASSWD FROM JMS_USERS WHERE USERID=?</module-option>
       <module-option name = "rolesQuery">SELECT ROLEID, 'Roles' FROM JMS_ROLES WHERE USERID=?</module-option>
    </login-module>
  </authentication>
</application-policy>