org.jboss.security.auth.spi

Class UsernamePasswordLoginModule

java.lang.Object

org.jboss.security.auth.spi.AbstractServerLoginModule

org.jboss.security.auth.spi.UsernamePasswordLoginModule

All Implemented Interfaces:

LoginModule

Direct Known Subclasses:

AnonLoginModule, DatabaseServerLoginModule, LdapExtLoginModule, LdapLoginModule, LdapUsersLoginModule, RegExUserNameLoginModule, RemoteHostTrustLoginModule, SAML2CommonLoginModule, SAML2LoginModule, SimpleServerLoginModule, UsersLoginModule, UsersRolesLoginModule, XMLLoginModule

public abstract class UsernamePasswordLoginModule
extends AbstractServerLoginModule

An abstract subclass of AbstractServerLoginModule that imposes an identity == String username, credentials == String password view on the login process.

Subclasses override the getUsersPassword() and getRoleSets() methods to return the expected password and roles for the user.

Version:

$Revision$

Author:

Scott.Stark@jboss.org

See Also:

getUsername(), getUsersPassword(), AbstractServerLoginModule.getRoleSets(), AbstractServerLoginModule.createIdentity(String)

Field Summary

Fields inherited from class org.jboss.security.auth.spi.AbstractServerLoginModule

callbackHandler, jbossModuleName, log, loginOk, options, principalClassModuleName, principalClassName, sharedState, subject, unauthenticatedIdentity, useFirstPass

Constructor Summary

Constructors

Constructor and Description
UsernamePasswordLoginModule()

Method Summary

Modifier and Type	Method and Description
protected String	createPasswordHash(String username, String password, String digestOption) If hashing is enabled, this method is called from login() prior to password validation.
protected Object	getCredentials()
protected Principal	getIdentity() Overriden by subclasses to return the Principal that corresponds to the user primary identity.
protected Principal	getUnauthenticatedIdentity()
protected String	getUsername()
protected String[]	getUsernameAndPassword() Called by login() to acquire the username and password strings for authentication.
protected abstract String	getUsersPassword() Get the expected password for the current username available via the getUsername() method.
protected Throwable	getValidateError() Get the error associated with the validatePassword failure
void	initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options) Override the superclass method to look for the following options after first invoking the super version.
boolean	login() Perform the authentication of the username and password.
protected void	safeClose(InputStream fis)
protected void	setValidateError(Throwable validateError) Set the error associated with the validatePassword failure
protected boolean	validatePassword(String inputPassword, String expectedPassword) A hook that allows subclasses to change the validation of the input password against the expected password.

Methods inherited from class org.jboss.security.auth.spi.AbstractServerLoginModule

abort, addValidOptions, checkOptions, commit, createGroup, createIdentity, getCallerPrincipalGroup, getRoleSets, getUseFirstPass, logout

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UsernamePasswordLoginModule

public UsernamePasswordLoginModule()

Method Detail

initialize

public void initialize(Subject subject,
                       CallbackHandler callbackHandler,
                       Map<String,?> sharedState,
                       Map<String,?> options)

Override the superclass method to look for the following options after first invoking the super version.

Specified by:

initialize in interface LoginModule

Overrides:

initialize in class AbstractServerLoginModule

Parameters:

options - : option: hashAlgorithm - the message digest algorithm used to hash passwords. If null then plain passwords will be used. option: hashCharset - the name of the charset/encoding to use when converting the password String to a byte array. Default is the platform's default encoding. option: hashEncoding - the string encoding format to use. Defaults to base64. option: ignorePasswordCase: A flag indicating if the password comparison should ignore case. option: digestCallback - The class name of the DigestCallback DigestCallback implementation that includes pre/post digest content like salts for hashing the input password. Only used if hashAlgorithm has been specified. option: hashStorePassword - A flag indicating if the store password returned from #getUsersPassword() should be hashed . option: hashUserPassword - A flag indicating if the user entered password should be hashed. option: storeDigestCallback - The class name of the DigestCallback 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.

subject - the Subject to update after a successful login.

callbackHandler - the CallbackHandler that will be used to obtain the the user identity and credentials.

sharedState - a Map shared between all configured login module instances

login

public boolean login()
              throws LoginException

Perform the authentication of the username and password.

Specified by:

login in interface LoginModule

Overrides:

login in class AbstractServerLoginModule

Throws:

LoginException

getIdentity

protected Principal getIdentity()

Description copied from class: AbstractServerLoginModule

Overriden by subclasses to return the Principal that corresponds to the user primary identity.

Specified by:

getIdentity in class AbstractServerLoginModule

getUnauthenticatedIdentity

protected Principal getUnauthenticatedIdentity()

Overrides:

getUnauthenticatedIdentity in class AbstractServerLoginModule

getCredentials

protected Object getCredentials()

getUsername

protected String getUsername()

getUsernameAndPassword

protected String[] getUsernameAndPassword()
                                   throws LoginException

Called by login() to acquire the username and password strings for authentication. This method does no validation of either.

Returns:

String[], [0] = username, [1] = password

Throws:

LoginException - thrown if CallbackHandler is not set or fails.

createPasswordHash

protected String createPasswordHash(String username,
                                    String password,
                                    String digestOption)
                             throws LoginException

If hashing is enabled, this method is called from login() prior to password validation.

Subclasses may override it to provide customized password hashing, for example by adding user-specific information or salting. If the legacyCreatePasswordHash option is set, this method tries to delegate to the legacy createPasswordHash(String, String) method via reflection and this is the value returned.

The default version calculates the hash based on the following options:

• hashAlgorithm: The digest algorithm to use.
• hashEncoding: The format used to store the hashes (base64 or hex)
• hashCharset: The encoding used to convert the password to bytes for hashing.
• digestCallback: The class name of the org.jboss.security.auth.spi.DigestCallback implementation that includes pre/post digest content like salts.

It will return null if the hash fails for any reason, which will in turn cause validatePassword() to fail.

Parameters:

username - ignored in default version

password - the password string to be hashed

digestOption - - the login module option name of the DigestCallback

Throws:

SecurityException - - thrown if there is a failure to load the digestOption DigestCallback

LoginException

getValidateError

protected Throwable getValidateError()

Get the error associated with the validatePassword failure

Returns:

the Throwable seen during validatePassword, null if no error occurred.

setValidateError

protected void setValidateError(Throwable validateError)

Set the error associated with the validatePassword failure

Parameters:

validateError -

validatePassword

protected boolean validatePassword(String inputPassword,
                                   String expectedPassword)

A hook that allows subclasses to change the validation of the input password against the expected password. This version checks that neither inputPassword or expectedPassword are null that that inputPassword.equals(expectedPassword) is true;

Returns:

true if the inputPassword is valid, false otherwise.

getUsersPassword

protected abstract String getUsersPassword()
                                    throws LoginException

Get the expected password for the current username available via the getUsername() method. This is called from within the login() method after the CallbackHandler has returned the username and candidate password.

Returns:

the valid password String

Throws:

LoginException

safeClose

protected void safeClose(InputStream fis)