org.jboss.security.auth.spi

Class AbstractServerLoginModule

java.lang.Object

org.jboss.security.auth.spi.AbstractServerLoginModule

All Implemented Interfaces:

LoginModule

Direct Known Subclasses:

AbstractPasswordCredentialLoginModule, BaseCertLoginModule, IdentityLoginModule, RoleMappingLoginModule, SAMLBearerTokenLoginModule, SAMLRoleLoginModule, SAMLTokenFromHttpRequestAbstractLoginModule, UsernamePasswordLoginModule

public abstract class AbstractServerLoginModule
extends Object
implements LoginModule

This class implements the common functionality required for a JAAS server side LoginModule and implements the JBossSX standard Subject usage pattern of storing identities and roles. Subclass this module to create your own custom LoginModule and override the login(), getRoleSets() and getIdentity() methods.

You may also wish to override

    public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options)
 

In which case the first line of your initialize() method should be:

    super.initialize(subject, callbackHandler, sharedState, options);
 

You may also wish to override

    public boolean login() throws LoginException
 

In which case the last line of your login() method should be

    return super.login();
 

Version:

$Revision$

Author:

Edward Kenworthy, 12th Dec 2000, Scott.Stark@jboss.org

Field Summary

Fields

Modifier and Type	Field and Description
protected CallbackHandler	callbackHandler
protected String	jbossModuleName jboss module name to load Callback class etc
protected Logger	log
protected boolean	loginOk Flag indicating if the login phase succeeded.
protected Map	options
protected String	principalClassModuleName
protected String	principalClassName An optional custom Principal class implementation
protected Map	sharedState
protected Subject	subject
protected Principal	unauthenticatedIdentity the principal to use when a null username and password are seen
protected boolean	useFirstPass Flag indicating if the shared credential should be used

Constructor Summary

Constructors

Constructor and Description
AbstractServerLoginModule()

Method Summary

Modifier and Type	Method and Description
boolean	abort() Method to abort the authentication process (phase 2).
protected void	addValidOptions(String[] moduleValidOptions) Each subclass should call this from within their initialize method BEFORE calling super.initialize() The base class will then check the options
protected void	checkOptions() checks the collected valid options against the options passed in Override when there are special needs like for the SimpleUsersLoginModule
boolean	commit() Method to commit the authentication process (phase 2).
protected Group	createGroup(String name, Set<Principal> principals) Find or create a Group with the given name.
protected Principal	createIdentity(String username) Utility method to create a Principal for the given username.
protected Group	getCallerPrincipalGroup(Set<Principal> principals)
protected abstract Principal	getIdentity() Overriden by subclasses to return the Principal that corresponds to the user primary identity.
protected abstract Group[]	getRoleSets() Overriden by subclasses to return the Groups that correspond to the to the role sets assigned to the user.
protected Principal	getUnauthenticatedIdentity()
protected boolean	getUseFirstPass()
void	initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options) Initialize the login module.
boolean	login() Looks for javax.security.auth.login.name and javax.security.auth.login.password values in the sharedState map if the useFirstPass option was true and returns true if they exist.
boolean	logout() Remove the user identity and roles added to the Subject during commit.

Methods inherited from class java.lang.Object

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

Field Detail

subject

protected Subject subject

callbackHandler

protected CallbackHandler callbackHandler

sharedState

protected Map sharedState

options

protected Map options

useFirstPass

protected boolean useFirstPass

Flag indicating if the shared credential should be used

loginOk

protected boolean loginOk

Flag indicating if the login phase succeeded. Subclasses that override the login method must set this to true on successful completion of login

principalClassName

protected String principalClassName

An optional custom Principal class implementation

principalClassModuleName

protected String principalClassModuleName

unauthenticatedIdentity

protected Principal unauthenticatedIdentity

the principal to use when a null username and password are seen

jbossModuleName

protected String jbossModuleName

jboss module name to load Callback class etc

log

protected Logger log

Constructor Detail

AbstractServerLoginModule

public AbstractServerLoginModule()

Method Detail

initialize

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

Initialize the login module. This stores the subject, callbackHandler and sharedState and options for the login session. Subclasses should override if they need to process their own options. A call to super.initialize(...) must be made in the case of an override.

Specified by:

initialize in interface LoginModule

Parameters:

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

options - the parameters passed to the login module.

login

public boolean login()
              throws LoginException

Looks for javax.security.auth.login.name and javax.security.auth.login.password values in the sharedState map if the useFirstPass option was true and returns true if they exist. If they do not or are null this method returns false. Note that subclasses that override the login method must set the loginOk ivar to true if the login succeeds in order for the commit phase to populate the Subject. This implementation sets loginOk to true if the login() method returns true, otherwise, it sets loginOk to false.

Specified by:

login in interface LoginModule

Throws:

LoginException

commit

public boolean commit()
               throws LoginException

Method to commit the authentication process (phase 2). If the login method completed successfully as indicated by loginOk == true, this method adds the getIdentity() value to the subject getPrincipals() Set. It also adds the members of each Group returned by getRoleSets() to the subject getPrincipals() Set.

Specified by:

commit in interface LoginModule

Returns:

true always.

Throws:

LoginException

See Also:

Subject;, Group;

abort

public boolean abort()
              throws LoginException

Method to abort the authentication process (phase 2).

Specified by:

abort in interface LoginModule

Returns:

true always

Throws:

LoginException

logout

public boolean logout()
               throws LoginException

Remove the user identity and roles added to the Subject during commit.

Specified by:

logout in interface LoginModule

Returns:

true always.

Throws:

LoginException

getIdentity

protected abstract Principal getIdentity()

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

getRoleSets

protected abstract Group[] getRoleSets()
                                throws LoginException

Overriden by subclasses to return the Groups that correspond to the to the role sets assigned to the user. Subclasses should create at least a Group named "Roles" that contains the roles assigned to the user. A second common group is "CallerPrincipal" that provides the application identity of the user rather than the security domain identity.

Returns:

Group[] containing the sets of roles

Throws:

LoginException

getUseFirstPass

protected boolean getUseFirstPass()

getUnauthenticatedIdentity

protected Principal getUnauthenticatedIdentity()

createGroup

protected Group createGroup(String name,
                            Set<Principal> principals)

Find or create a Group with the given name. Subclasses should use this method to locate the 'Roles' group or create additional types of groups.

Returns:

A named Group from the principals set.

createIdentity

protected Principal createIdentity(String username)
                            throws Exception

Utility method to create a Principal for the given username. This creates an instance of the principalClassName type if this option was specified using the class constructor matching: ctor(String). If principalClassName was not specified, a SimplePrincipal is created.

Parameters:

username - the name of the principal

Returns:

the principal instance

Throws:

Exception - thrown if the custom principal type cannot be created.

getCallerPrincipalGroup

protected Group getCallerPrincipalGroup(Set<Principal> principals)

addValidOptions

protected void addValidOptions(String[] moduleValidOptions)

Each subclass should call this from within their initialize method BEFORE calling super.initialize() The base class will then check the options

Parameters:

moduleValidOptions - : the list of options the subclass supports

checkOptions

protected void checkOptions()

checks the collected valid options against the options passed in Override when there are special needs like for the SimpleUsersLoginModule