SK.gnome.dwarf.auth.login
Class GenericLoginModule

java.lang.Object
  SK.gnome.dwarf.auth.login.GenericLoginModule

All Implemented Interfaces:

javax.security.auth.spi.LoginModule

Direct Known Subclasses:

DenyLoginModule, JDBCLoginModule, PermitLoginModule, PlaintextLoginModule, UnixLoginModule

public abstract class GenericLoginModule

extends java.lang.Object

implements javax.security.auth.spi.LoginModule

This class provides a generic login module.

The validate(String, char[]) method must be implemented by all extending classes. This method should validate the user according to the given username and password. The password can be tested via the checkPassword(String, char[]) method using the given PasswordEncoder implementation. The default password encoder used is the MD5PasswordEncoder, but other implementations may be specified also via the encoder option key in the module configuration. Use a full name of the encoder class as the key value.

The option key debug can be also specified for a modules based on this class. See the debug(String) and isDebugOn() methods for the exact meaning. The default key value is false.

The option key ignorecase can be specified for a modules based on this class, too. The isIgnoreCaseOn() method may be consulted by the subclasses to decide whether or not the module may perform case-insensitive logins. The default key value is false.

A sample login module configuration entry may look like this:

 Test {
   SK.gnome.dwarf.auth.login.PlaintextLoginModule required
     debug="true"
     ignorecase="true"
     encoder="SK.gnome.dwarf.auth.login.CryptPasswordEncoder";
 };
 

An option key ident may be also supported for a particular module implementation. If it is set to "true", the module should be able to perform identification instead of an authentication. To support this, the validate(String, char[]) method must be implemented in a way that if the password argument is null, it will only test the given user for existence and eventually return its various identities in the array of principal objects. In this case the password check must be bypassed by the method. This enables the application code just to test if the given user is valid, and eventually to obtain also its various security roles. This is suitable in the situations when we need to validate a user without knowing any of her security credentials (password, certificate, etc.) However, subjects processed by this type of authentication must not be regarder as a fully authenticated subjects. The option key value is therefore false by default.

A sample login module configuration entry enabling the identification feature:

 Ident {
   SK.gnome.dwarf.auth.login.MyLoginModule required ident="true";
 };
 

A sample code using the identification and authentication:

 Subject subject = new Subject();
 
 // performs only identification
 try
 { login("Ident", subject, new BasicCallbackHandler("joe");  // no password is given
   // user is valid
 }
 catch (LoginException e)
 { // user is not valid
 }

 subject = new Subject();
 
 // performs full authentication
 try
 { login("Ident", subject, new BasicCallbackHandler("joe", "password");
   // user is authenticated
 }
 catch (LoginException e)
 { // user is not authenticated
 }
 

Field Summary

protected java.lang.Class

encoder The password encoder used by this module.

Constructor Summary

GenericLoginModule()

Method Summary

boolean	abort() This method is called if the LoginContext's overall authentication failed (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL login modules did not succeed).
boolean	commit() This method is called if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL login modules succeeded).
protected void	debug(java.lang.String message) Prints a debugging message to the standard output.
protected boolean	getBooleanOption(java.lang.String name, boolean defaultValue) Returns an option key value as a boolean.
protected int	getIntOption(java.lang.String name, int defaultValue) Returns an option key value as an integer.
protected java.lang.String	getStringOption(java.lang.String name, java.lang.String defaultValue) Returns an option key value as a string.
protected boolean	checkPassword(java.lang.String encoded, char[] plain) Checks the given password.
void	initialize(javax.security.auth.Subject subject, javax.security.auth.callback.CallbackHandler callbackHandler, java.util.Map sharedState, java.util.Map options) Initializes this login module.
protected boolean	isDebugOn() Whether the debugging messages are enabled.
protected boolean	isIdentOn() Whether the identification feature is enabled.
protected boolean	isIgnoreCaseOn() Whether the module may perform a case-insensitive logins.
boolean	login() Authenticates the user.
boolean	logout() Logouts the user.
protected abstract java.security.Principal[]	validate(java.lang.String username, char[] password) Validates the given user.

Methods inherited from class java.lang.Object

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

Field Detail

encoder

protected java.lang.Class encoder

The password encoder used by this module.

Constructor Detail

GenericLoginModule

public GenericLoginModule()

Method Detail

initialize

public void initialize(javax.security.auth.Subject subject,
                       javax.security.auth.callback.CallbackHandler callbackHandler,
                       java.util.Map sharedState,
                       java.util.Map options)

Initializes this login module.

Specified by:

initialize in interface javax.security.auth.spi.LoginModule

Parameters:

subject - the subject to be authenticated

callbackHandler - the callbackHandler for getting the username and password

sharedState - shared login module state

options - options specified in the login configuration for this particular login module

login

public boolean login()
              throws javax.security.auth.login.LoginException

Authenticates the user.

This method uses NameCallback and PasswordCallback to gather the user credentials via CallbackHandler, then it calls the validate(String, char[]) method to perform the actual user validation.

Specified by:

login in interface javax.security.auth.spi.LoginModule

Returns:

true in all cases since this login module should not be ignored

Throws:

javax.security.auth.login.FailedLoginException - if the authentication fails

javax.security.auth.login.LoginException - if this login module is unable to perform the authentication

commit

public boolean commit()
               throws javax.security.auth.login.LoginException

This method is called if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL login modules succeeded).

If this login module's own authentication attempt succeeded (checked by retrieving the private state saved by the login() method), then this method associates all principal objects returned from the validate(String, char[]) method with the Subject instance.
If this login module's own authentication attempt failed, then this method removes any state that was originally saved.

Specified by:

commit in interface javax.security.auth.spi.LoginModule

Returns:

true if this login module's own login and commit attempts succeeded, or false otherwise.

Throws:

javax.security.auth.login.LoginException - if the commit fails

abort

public boolean abort()
              throws javax.security.auth.login.LoginException

This method is called if the LoginContext's overall authentication failed (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL login modules did not succeed).

If this login module's own authentication attempt succeeded (checked by retrieving the private state saved by the login() and commit() methods), then this method cleans up any state that was originally saved.

Specified by:

abort in interface javax.security.auth.spi.LoginModule

Returns:

false if this login module's own login and/or commit attempts failed, and true otherwise.

Throws:

javax.security.auth.login.LoginException - if the abort fails.

logout

public boolean logout()
               throws javax.security.auth.login.LoginException

Logouts the user.

This method removes the principal objects that were added by the commit() method from the Subject instance.

Specified by:

logout in interface javax.security.auth.spi.LoginModule

Returns:

true in all cases since this login module should not be ignored.

Throws:

javax.security.auth.login.LoginException - if the logout fails

getStringOption

protected java.lang.String getStringOption(java.lang.String name,
                                           java.lang.String defaultValue)

Returns an option key value as a string.

If no option with the given name can be found, the defaultValue is returned.

Parameters:

name - the option's name

defaultValue - the default value

Returns:

the option value

getIntOption

protected int getIntOption(java.lang.String name,
                           int defaultValue)

Returns an option key value as an integer.

If no option with the given name can be found, the defaultValue is returned.

Parameters:

name - the option's name

defaultValue - the default value

Returns:

the option value

getBooleanOption

protected boolean getBooleanOption(java.lang.String name,
                                   boolean defaultValue)

Returns an option key value as a boolean.

Returns true if the option is found and its value equals to "true" or "on", otherwise returns false

Parameters:

name - the option's name

defaultValue - the default value

Returns:

the option value

debug

protected void debug(java.lang.String message)

Prints a debugging message to the standard output.

The message is printed only if the isDebugOn() method returns true.

Parameters:

message - debugging message

isDebugOn

protected boolean isDebugOn()

Whether the debugging messages are enabled.

Returns true if the debugging messages were enabled for this module via the debug option key, otherwise returns false.

Returns:

true if debugging is enabled

isIdentOn

protected boolean isIdentOn()

Whether the identification feature is enabled.

Returns true if the identification feature was enabled for this module via the ident* option key, otherwise returns false.

Returns:

true if identification is enabled

isIgnoreCaseOn

protected boolean isIgnoreCaseOn()

Whether the module may perform a case-insensitive logins.

Returns true if the case-insensitive login was enabled for this module via the ignorecase option key, otherwise returns false.

Returns:

true if case-insensitive login is permitted

checkPassword

protected boolean checkPassword(java.lang.String encoded,
                                char[] plain)
                         throws javax.security.auth.login.LoginException

Checks the given password.

Checks whether or not the encoded password equals to the plain (non-encoded) password.

This method allows the login module to check passwords encoded by various different algorithms by using a custom password encoder. The password encoder must be a class implementing the PasswordEncoder interface. The default encoder used is the MD5PasswordEncoder, and a custom encoder may be specified via the encoder option key by providing its full class name.

This method calls the PasswordEncoder.compare(String, char[]) method of the current PasswordEncoder with the corresponding arguments.

Parameters:

encoded - the encoded password

plain - the plain (non-encoded) password

Returns:

true if passwords are equal, false otherwise

Throws:

javax.security.auth.login.LoginException - if an error ocurred

validate

protected abstract java.security.Principal[] validate(java.lang.String username,
                                                      char[] password)
                                               throws javax.security.auth.login.LoginException

Validates the given user.

This method must validate a user according to the given username and password, and should return an array of principal objects representing the various user's identities. If no principals are found, an empty array must be returned. If the user could not be validated, a LoginException is thrown to indicate the failed login. Exception is then propagated to the calling LoginContext object.

It is recommended for the implementations to use the checkPassword(String, char[]) method to validate the password using the current PasswordEncoder instance.

This method may be implemented in a way that if the password argument is null, it will bypass the password check and will test the user existence only. However, the subject procesed by this type of authentication must not be used to represent an authenticated user. The implementations must consult the ident option key prior to enabling this feature.

The ignorecase option key may be consulted by the implementing modules, too, for enabling the case-insensitive logins.

Parameters:

username - the name of the user

password - the user password

Returns:

the array of principals representing the various user identities

Throws:

javax.security.auth.login.LoginException