org.n52.security.authentication.loginmodule
Class AbstractLoginModule

java.lang.Object
  extended by org.n52.security.authentication.loginmodule.AbstractLoginModule
All Implemented Interfaces:
java.io.Serializable, javax.security.auth.spi.LoginModule
Direct Known Subclasses:
AbstractPasswordLoginModule, SAMLTicketLoginModule

public abstract class AbstractLoginModule
extends java.lang.Object
implements javax.security.auth.spi.LoginModule, java.io.Serializable

Class AbstractLoginModule is a abstract base class for login modules.

It implements the methods

in an open manner to support a simpler and error free implementation of concrete login modules.

Sub classes have to implement the methods initialize(), clearAuthenticationState(), performLogin() and prepareCommitState().

Within the initialize method the login module can check given options and the shared state for context information.

In the performLogin method the login module performs the login, which means that it checks the authentication credentials.

The prepareCommitState method is invoked during the commit phase of the authentication. Therein a login module can store all principals and credentials for the user in the local principal and credentail sets ( addPrincipal(java.security.Principal), (addPrivateCredential(Object) and ( addPublicCredential(Object)). These will automatically applied to the user and removed in the logout() and abort() methods.

The clearAuthenticationState method is invoked to tell a login module to release any authentication information obtained from the user.

This class implements Serializable to make it possible to store LoginContexts for a subject for a longer time. Not all fields can be serialized e.g. the CallbackHandler is omitted, therewith it makes only sense to serialize authenticated login contexts, e.g. for later logout in a web application. Successfull serialization requires also serializable credentials and principals.

Version:
$Revision: $
Author:
Marko Reiprecht Created on 15.09.2007
See Also:
LoginModule Developer's Guide , Serialized Form

Field Summary
protected  javax.security.auth.callback.CallbackHandler m_callbackHandler
          Field m_callbackHandler holds the CallbackHandler.
protected  boolean m_commitSucceeded
          Field m_commitSucceeded is a flat wich indicates a successfull execution of the commit method.
protected  boolean m_loginSucceeded
          Field m_loginSucceeded is a flag wich indicates a successfull execution of the login method.
protected  Options m_options
          Field m_options holds the options of the login module.
protected  java.util.Set m_principals
          Field m_principals contains the principals, which shall or were applied to the subject.
protected  java.util.Set m_privateCredentials
          Field m_privateCredentials contains the private credentials, which are created by this login module and shall or were applied to the subject.
protected  java.util.Set m_publicCredentials
          Field m_publicCredentials contains the public credentials, which are created by this login module and shall or were applied to the subject.
protected  SharedState m_sharedState
          Field m_sharedState holds the shared state.
protected  javax.security.auth.Subject m_subject
          Field m_subject holds the Subject.
 
Constructor Summary
AbstractLoginModule()
           
 
Method Summary
 boolean abort()
          Method aborts the authentication process.
protected  void addPrincipal(java.security.Principal principal)
          Method adds a principal to the local principal set.
protected  void addPrivateCredential(java.lang.Object credential)
          Method adds a private credential to the local private credential set.
protected  void addPublicCredential(java.lang.Object credential)
          Method adds a public credential to the local public credential set.
protected abstract  void clearAuthenticationState()
          Method cleanAuthenticationState is a template method used to invoke a cleanup of any authentication information provided by the user e.g. the user name and password used to login the user.
protected  boolean clearInternalState()
          Method clearInternalState clears all internal principals and credentials and sets the state of loginSucceeded and commitSucceeded back to false and clears all references to external resouces (e.g.
 boolean commit()
          Method commit checks if the login succeeded and if true it calls commitState() to apply all principals and credentials to the subject.
protected  boolean commitState()
          Method commitState applies all principals, public and private credentials created during the login or the prepareCommitState method to the subject and sets the internal commitSucceded state to true.
protected  boolean destroy(java.util.Set destroyables)
          Method destroy checks the set for instances of Destroyable and destroys them.
protected  javax.security.auth.callback.CallbackHandler getCallbackHandler()
          Method gets the callbackHandler.
protected abstract  java.lang.String getDescription()
          Method gets the description of this LoginModule.
protected  Options getOptions()
          Method gets the options of this AbstractLoginModule object.
protected  java.util.Set getPrincipals()
          Method gets the principals created during the login method.
protected  java.util.Set getPrivateCredentials()
          Method gets the privateCredentials created during the login method.
protected  java.util.Set getPublicCredentials()
          Method gets the publicCredentials created during the login method.
protected  SharedState getSharedState()
          Method gets the sharedState of this login context.
protected  javax.security.auth.Subject getSubject()
          Method gets the subject of this login context.
protected  void handleCallbacks(javax.security.auth.callback.Callback[] callbacks)
          Method handleCallbacks sends the given callback array to the callback handler.
protected abstract  void initialize()
          Method initialize replaces the LoginModule.initialize( javax.security.auth.Subject,javax.security.auth.callback.CallbackHandler,java.util.Map,java.util.Map) .
 void initialize(javax.security.auth.Subject subject, javax.security.auth.callback.CallbackHandler callbackHandler, java.util.Map sharedState, java.util.Map options)
          Method initialize the login module.
protected  boolean isCallbackHandlerSet()
          Method gets the callbackHandlerSet of this AbstractLoginModule object.
protected  boolean isCommitSucceeded()
          Method gets the commitSucceeded flag.
protected  boolean isLoginSucceeded()
          Method gets the loginSucceeded flag.
 boolean login()
          Method checks the some default settings before it delegates to the performLogin method.
 boolean logout()
          Method logout releases all state information applied during a commit from the subject.
protected abstract  boolean performLogin()
          Method performs the real login, this is called by the pre implented login() method.
protected abstract  void prepareCommitState()
          Method prepareCommitState is a template method used to let a sub class prepare all principals and credentials, which then will be applied to the subject.
protected  void setCommitSucceeded(boolean commitSucceeded)
          Method sets the commit succeeded state of the login module.
protected  void setLoginSucceeded(boolean loginSucceeded)
          Method sets the login succeeded state of the login module.
protected  void showModuleBanner()
          Method showModuleBanner sends a description of the login module to the callback handler.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

m_subject

protected javax.security.auth.Subject m_subject
Field m_subject holds the Subject.

See Also:
getSubject()

m_callbackHandler

protected transient javax.security.auth.callback.CallbackHandler m_callbackHandler
Field m_callbackHandler holds the CallbackHandler.

See Also:
getCallbackHandler(), isCallbackHandlerSet()

m_sharedState

protected SharedState m_sharedState
Field m_sharedState holds the shared state.

See Also:
getSharedState()

m_options

protected Options m_options
Field m_options holds the options of the login module.

See Also:
getOptions()

m_principals

protected java.util.Set m_principals
Field m_principals contains the principals, which shall or were applied to the subject.


m_publicCredentials

protected java.util.Set m_publicCredentials
Field m_publicCredentials contains the public credentials, which are created by this login module and shall or were applied to the subject.


m_privateCredentials

protected java.util.Set m_privateCredentials
Field m_privateCredentials contains the private credentials, which are created by this login module and shall or were applied to the subject.


m_loginSucceeded

protected boolean m_loginSucceeded
Field m_loginSucceeded is a flag wich indicates a successfull execution of the login method.


m_commitSucceeded

protected boolean m_commitSucceeded
Field m_commitSucceeded is a flat wich indicates a successfull execution of the commit method.

Constructor Detail

AbstractLoginModule

public AbstractLoginModule()
Method Detail

getCallbackHandler

protected javax.security.auth.callback.CallbackHandler getCallbackHandler()
Method gets the callbackHandler. It can be null if the application does not set one.

Returns:
CallbackHandler | null

getOptions

protected Options getOptions()
Method gets the options of this AbstractLoginModule object.

Returns:
Options.

getPrincipals

protected java.util.Set getPrincipals()
Method gets the principals created during the login method.

Returns:
Set of Principal classes.

getPrivateCredentials

protected java.util.Set getPrivateCredentials()
Method gets the privateCredentials created during the login method.

Returns:
Set of credentials -> type is unknown and specific to the login module.

getPublicCredentials

protected java.util.Set getPublicCredentials()
Method gets the publicCredentials created during the login method.

Returns:
Set of credentials -> type is unknown and specific to the login module.

getSharedState

protected SharedState getSharedState()
Method gets the sharedState of this login context.

Returns:
SharedState.

getSubject

protected javax.security.auth.Subject getSubject()
Method gets the subject of this login context.

Returns:
Subject.

isCommitSucceeded

protected boolean isCommitSucceeded()
Method gets the commitSucceeded flag. This is must be true only if the commit method was executed successfull.

Returns:
boolean.

setCommitSucceeded

protected void setCommitSucceeded(boolean commitSucceeded)
Method sets the commit succeeded state of the login module. This must be called with a value of true if the commit method of a subclass succeeded.

Parameters:
commitSucceeded - (true|false)

isLoginSucceeded

protected boolean isLoginSucceeded()
Method gets the loginSucceeded flag. This must be true only if the login method was executed successfull.

Returns:
boolean.

setLoginSucceeded

protected void setLoginSucceeded(boolean loginSucceeded)
Method sets the login succeeded state of the login module. This must be called with a m_value of true if the login method of a subclass succeeded.

Parameters:
loginSucceeded - (true|false).

abort

public boolean abort()
              throws javax.security.auth.login.LoginException
Method aborts the authentication process.

Specified by:
abort in interface javax.security.auth.spi.LoginModule
Returns:
boolean.
Throws:
javax.security.auth.login.LoginException - if error occurs.
See Also:
Description of the abort method in the LoginModule Developer's Guide

commit

public boolean commit()
               throws javax.security.auth.login.LoginException
Method commit checks if the login succeeded and if true it calls commitState() to apply all principals and credentials to the subject.

Specified by:
commit in interface javax.security.auth.spi.LoginModule
Returns:
boolean true if commit succeeded.
Throws:
javax.security.auth.login.LoginException - if error occurs.
See Also:
Description of the commit method in the LoginModule Developer's Guide

logout

public boolean logout()
               throws javax.security.auth.login.LoginException
Method logout releases all state information applied during a commit from the subject.

Specified by:
logout in interface javax.security.auth.spi.LoginModule
Returns:
boolean.
Throws:
javax.security.auth.login.LoginException - if error occurs.
See Also:
Description of the logout method in the LoginModule Developer's Guide

login

public boolean login()
              throws javax.security.auth.login.LoginException
Method checks the some default settings before it delegates to the performLogin method. It checks if the loginmodule is disabled and that a call backhandler is provided.

Specified by:
login in interface javax.security.auth.spi.LoginModule
Returns:
boolean.
Throws:
javax.security.auth.login.LoginException - if error occurs.

performLogin

protected abstract boolean performLogin()
                                 throws javax.security.auth.login.LoginException
Method performs the real login, this is called by the pre implented login() method.

Returns:
boolean.
Throws:
javax.security.auth.login.LoginException - if error occurs.
See Also:
Description of the login method in the LoginModule Developer's Guide

initialize

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

All parameters are stored in internal variables, accessible with getter methods. The sharedState and options parameter maps are wrapped with special classes SharedState and Options.

Specified by:
initialize in interface javax.security.auth.spi.LoginModule
Parameters:
subject - the subject.
callbackHandler - the callbackHandler can be null.
sharedState - the sharedState map.
options - the options map.
See Also:
LoginModule.initialize( javax.security.auth.Subject,javax.security.auth.callback.CallbackHandler,java.util.Map,java.util.Map), Description of the initialize method in the LoginModule Developer's Guide

addPrincipal

protected void addPrincipal(java.security.Principal principal)
Method adds a principal to the local principal set. The principals will be added to the subject in the commit method and removed from the subject on logout or abort.

Parameters:
principal - a principal created during login.

addPrivateCredential

protected void addPrivateCredential(java.lang.Object credential)
Method adds a private credential to the local private credential set. The credentials will be added to the subject in the commit method and removed from the subject on logout or abort.

Parameters:
credential - a private credential created during login.

addPublicCredential

protected void addPublicCredential(java.lang.Object credential)
Method adds a public credential to the local public credential set. The credentials will be added to the subject in the commit method and removed from the subject on logout or abort.

Parameters:
credential - a public credential created during login.

clearInternalState

protected boolean clearInternalState()
                              throws javax.security.auth.login.LoginException
Method clearInternalState clears all internal principals and credentials and sets the state of loginSucceeded and commitSucceeded back to false and clears all references to external resouces (e.g. CallbackHandler). It also invokes the clearAuthenticationState() method to ensure that no user credentials are further stored.

Returns:
boolean.
Throws:
javax.security.auth.login.LoginException - if error occurs.

clearAuthenticationState

protected abstract void clearAuthenticationState()
                                          throws javax.security.auth.login.LoginException
Method cleanAuthenticationState is a template method used to invoke a cleanup of any authentication information provided by the user e.g. the user name and password used to login the user.

This is not a clean up of the created principals or credentials during login. It is a way to reduce the security holes by cleaning state information wich is not further needed.

Throws:
javax.security.auth.login.LoginException - if an error occurs.

commitState

protected boolean commitState()
                       throws javax.security.auth.login.LoginException
Method commitState applies all principals, public and private credentials created during the login or the prepareCommitState method to the subject and sets the internal commitSucceded state to true. It also calls clearAuthenticationState().

Returns:
boolean.
Throws:
javax.security.auth.login.LoginException - if commit fails e.g. because the subject is readonly.
See Also:
login(), addPrincipal(java.security.Principal), addPrivateCredential(Object), addPublicCredential(Object)

prepareCommitState

protected abstract void prepareCommitState()
                                    throws javax.security.auth.login.LoginException
Method prepareCommitState is a template method used to let a sub class prepare all principals and credentials, which then will be applied to the subject.

It allows to separate the logic of the login (retrieve and check the authentication credentials) from the logic for retrieving/preparing subject information.

Throws:
javax.security.auth.login.LoginException - if error occurs.

destroy

protected boolean destroy(java.util.Set destroyables)
Method destroy checks the set for instances of Destroyable and destroys them.

The method only returns true if all instances within the set are Destroyables and the destroy method succeeded on all.

Parameters:
destroyables - the destroyables.
Returns:
boolean flag indicates that all instances are destroyed.

initialize

protected abstract void initialize()
Method initialize replaces the LoginModule.initialize( javax.security.auth.Subject,javax.security.auth.callback.CallbackHandler,java.util.Map,java.util.Map) .

All parameters of the original initialize method can be retrieved by getter methods.

A subclasses shall check the options and initializes them self.

See Also:
LoginModule.initialize( javax.security.auth.Subject,javax.security.auth.callback.CallbackHandler,java.util.Map,java.util.Map), Description of the initialize method in the LoginModule Developer's Guide

isCallbackHandlerSet

protected boolean isCallbackHandlerSet()
Method gets the callbackHandlerSet of this AbstractLoginModule object.

Returns:
boolean.

showModuleBanner

protected void showModuleBanner()
                         throws javax.security.auth.login.LoginException
Method showModuleBanner sends a description of the login module to the callback handler. This method shall be used in login methods if the option Options.isModuleBanner() is set.

Throws:
javax.security.auth.login.LoginException - if a error occurs within the callback handler during this operation.
See Also:
Options.OPTION_MODULEBANNER

getDescription

protected abstract java.lang.String getDescription()
Method gets the description of this LoginModule.

The description is used if the login module is configured with the option 'moduleBanner', to invoke a TextOutputCallback on the callback handler.

Returns:
String.
See Also:
Options.OPTION_MODULEBANNER, showModuleBanner()

handleCallbacks

protected void handleCallbacks(javax.security.auth.callback.Callback[] callbacks)
                        throws javax.security.auth.login.LoginException
Method handleCallbacks sends the given callback array to the callback handler.

It converts a eventually thrown IOException or UnsuportedCallbackException to a LoginException, therefore use this method only if there is no other possible reaction to the exceptions thrown by the CallbackHandler.

Parameters:
callbacks - the callbacks to execute.
Throws:
javax.security.auth.login.LoginException - if error occurs in the callback handler.


Copyright © 2004-2009 52north.org. All Rights Reserved.