Chapter 2. Abstract Login Modules

The abstract login modules are abstract Java classes that are extended by the other login modules in order to provide common functionality and configuration options. The abstract login modules may never be used directly, but the configuration options are available to any login modules that extend them.

2.1. AbstractServer Login Module

Short name: AbstractServerLoginModule

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

The AbstractServer Login Module serves as a base class for many login modules as well as several abstract login modules. It implements the common functionality required for a JAAS server side login module and implements the PicketBox standard Subject usage pattern of storing identities and roles.

OptionTypeDefaultDescription

principalClass

A fully qualified classname

org.jboss.security.SimplePrincipal

A Principal implementation class which contains a constructor that takes String argument for the principal name.

module

String

none

A reference to a jboss-module that can be used to load a custom callback/validator.

unauthenticatedIdentity

String

none

This defines the principal name that should be assigned to requests that contain no authentication information. This can allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and can only access unsecured EJBs or EJB methods that are associated with the unchecked permission constraint. See the Unauthenticated Identity section for more details.

password-stacking

useFirstPass or false

false

See the Password Stacking section for more details.

2.1.1. Unauthenticated Identity

Not all requests are received in an authenticated format. The unauthenticatedIdentity login module configuration assigns a specific identity, guest for example, to requests that are made with no associated 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. For example, this configuration option can be used in the UsersRoles and Remoting Login Modules

2.1.2. Password Stacking

Multiple login modules can be chained together in a stack, with each login module providing both the credentials verification and role assignment during authentication. This works for many use cases, but sometimes credentials verification and role assignment are split across multiple user management stores.

Consider the case where users are managed in a central LDAP server but application-specific roles are stored in the application’s relational database. The password-stacking module option captures this relationship.

To use password stacking, each login module should set the password-stacking attribute to useFirstPass, which is located in the <module-option> section. If a previous module configured for password stacking has authenticated the user, all the other stacking modules will consider the user authenticated and only attempt to provide a set of roles for the authorization step.

When password-stacking option is set to useFirstPass, this module first looks for a shared user name 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 properties 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.

Note

When using password stacking, set all modules to be required. This ensures that all modules are considered, and have the chance to contribute roles to the authorization process.

2.2. UsernamePassword Login Module

Short name: UsernamePasswordLoginModule

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

Parent: AbstractServer Login Module

The UsernamePassword Login Module is an abstract login module that imposes an identity == String username, credentials == String password view on the login process. It inherits all the fields from Abstract Server login module in addition to the below fields.

OptionTypeDefaultDescription

ignorePasswordCase

boolean

false

A flag indicating if the password comparison should ignore case.

digestCallback

A fully qualified classname

none

The class name of the org.jboss.crypto.digest.DigestCallback implementation that includes pre/post digest content like salts for hashing the input password. Only used if hashAlgorithm has been specified and hashUserPassword is set to true.

storeDigestCallback

A fully qualified classname

none

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

throwValidateError

boolean

false

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

inputValidator

A fully qualified classname

none

The instance of the org.jboss.security.auth.spi.InputValidator implementation used to validate the user name and password supplied by the client.

Note

The UsernamePassword Login Module options, regarding password hashing, are described in the next section.

2.2.1. Password Hashing

Most login modules must compare a client-supplied password to a password stored in a user management system. These modules generally work with plain text passwords, but can be configured to support hashed passwords to prevent plain text passwords from being stored on the server side. JBoss EAP supports the ability to configure the hashing algorithm, encoding, and character set as well as when the user password and store password are hashed.

The following are password hashing options that can be configured as part of a login module that has UsernamePassword Login Module as a parent:

OptionTypeDefaultDescription

hashAlgorithm

String representing a password hashing algorithm.

none

Name of the java.security.MessageDigest algorithm to be used to hash the password. There is no default so this option must be specified to enable hashing. Typical values are SHA-256, SHA-1 and MD5. When hashAlgorithm is specified and hashUserPassword is set to true, the clear text password obtained from the CallbackHandler is hashed before it is passed to UsernamePasswordLoginModule.validatePassword as the inputPassword argument.

hashEncoding

String

base64

The string format for the hashed password, if hashAlgorithm is also set. May specify one of three encoding types: base64, hex or rfc2617.

hashCharset

String

The default encoding set in the container’s runtime environment

The name of the charset/encoding to use when converting the password string to a byte array.

hashUserPassword

boolean

true

A flag indicating if the user entered password should be hashed. The hashed user password is compared against the value in the login module, which is expected to be a hash of the password.

hashStorePassword

boolean

false

A flag indicating if the store password returned should be hashed. This is used for digest authentication, where the user submits a hash of the user password along with a request-specific tokens from the server to be compared. The hash algorithm, for digest, this would be rfc2617, is utilized to compute a server-side hash, which should match the hashed value sent from the client.

passwordIsA1Hash

boolean

 

A flag used by the org.jboss.security.auth.callback.RFC2617Digest when it is configured as the digestCallback or storeDigestCallback. If true, incoming password will not be hashed since it is already hashed.

2.3. AbstractPasswordCredential Login Module

Short name: AbstractPasswordCredentialLoginModule

Full name: org.picketbox.datasource.security.AbstractPasswordCredentialLoginModule

Parent: AbstractServer Login Module

AbstractPasswordCredential Login Module is a base login module that handles PasswordCredentials.

2.4. Common Login Module

Short name: CommonLoginModule

Full name: org.jboss.security.negotiation.common.CommonLoginModule

Parent: AbstractServer Login Module

Common Login Module is an abstract login module that serves as a base login module for some login modules within JBoss Negotiation.