org.apache.jackrabbit.core.security.authentication
Class AbstractLoginModule

java.lang.Object
  org.apache.jackrabbit.core.security.authentication.AbstractLoginModule

All Implemented Interfaces:

LoginModule

Direct Known Subclasses:

DefaultLoginModule, SimpleLoginModule

public abstract class AbstractLoginModule
extends Object
implements LoginModule

AbstractLoginModule provides the means for the common authentication tasks within the Repository.

On successfull authentication it associates the credentials to principals using the PrincipalProvider configured for this LoginModule

Jackrabbit distinguishes between Login and Impersonation dispatching the the correspoding Repository/Session methods to authenticate(java.security.Principal, javax.jcr.Credentials) and impersonate(java.security.Principal, javax.jcr.Credentials), respectively.
This LoginModule implements default behaviors for both methods.

See Also:

LoginModule

Field Summary

protected String	adminId
protected String	anonymousId
protected SimpleCredentials	credentials
protected Principal	principal
protected PrincipalProvider	principalProvider
protected Subject	subject

Constructor Summary

AbstractLoginModule()

Method Summary

boolean	abort() Method to abort the authentication process (phase 2).
protected boolean	authenticate(Principal principal, Credentials credentials)
boolean	commit() Method to commit the authentication process (phase 2).
protected abstract void	doInit(CallbackHandler callbackHandler, Session session, Map options) Implementations may set-up their own state.
String	getAdminId() Returns the admin user id.
String	getAnonymousId() Returns the anonymous user id.
protected abstract Authentication	getAuthentication(Principal principal, Credentials creds)
protected Credentials	getCredentials() Method tries to resolve the Credentials used for login.
protected Subject	getImpersonatorSubject(Credentials credentials) Method tries to acquire an Impersonator in the follwing order: Try to access it from the Credentials via SimpleCredentials.getAttribute(String) Ask CallbackHandler for Impersonator with use of ImpersonationCallback.
protected abstract Principal	getPrincipal(Credentials credentials) Authentication process associates a Principal to Credentials This method resolves the Principal for the given Credentials.
String	getPrincipalProvider() Returns the configured name of the principal provider class.
protected Set	getPrincipals()
protected String	getUserID(Credentials credentials) Method supports tries to acquire a UserID in the follwing order: If passed credentials are GuestCredentials the anonymous user id is returned.
protected abstract boolean	impersonate(Principal principal, Credentials credentials) Handles the impersonation of given Credentials.
void	initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) Initialize this LoginModule.
protected boolean	isAnonymous(Credentials credentials) Indicate if the given Credentials are considered to be anonymous.
protected boolean	isImpersonation(Credentials credentials) Test if the current request is an Impersonation attempt.
protected boolean	isInitialized() Returns true if this module has been successfully initialized.
boolean	login() Method to authenticate a Subject (phase 1).
boolean	logout() Method which logs out a Subject.
void	setAdminId(String adminId) Sets the administrator's user id.
void	setAnonymousId(String anonymousId) Sets the anonymous user id.
void	setPrincipalProvider(String principalProvider) Sets the configured name of the principal provider class

Methods inherited from class java.lang.Object

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

Field Detail

adminId

protected String adminId

anonymousId

protected String anonymousId

principal

protected Principal principal

credentials

protected SimpleCredentials credentials

subject

protected Subject subject

principalProvider

protected PrincipalProvider principalProvider

Constructor Detail

AbstractLoginModule

public AbstractLoginModule()

Method Detail

initialize

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

Initialize this LoginModule.
This abstract implementation, initalizes the following fields for later use:

• PrincipalManager for group-membership resoultion
• PrincipalProvider for user-Principal resolution.
• LoginModuleConfig.PARAM_ADMIN_ID option is evaluated
• LoginModuleConfig.PARAM_ANONYMOUS_ID option is evaluated

Implementations are called via doInit(CallbackHandler, Session, Map) to implement additional initalization

Specified by:

initialize in interface LoginModule

Parameters:

subject - the Subject to be authenticated.

callbackHandler - a CallbackHandler for communicating with the end user (prompting for usernames and passwords, for example).

sharedState - state shared with other configured LoginModules.

options - options specified in the login Configuration for this particular LoginModule.

See Also:

LoginModule.initialize(Subject, CallbackHandler, Map, Map), doInit(CallbackHandler, Session, Map), isInitialized()

doInit

protected abstract void doInit(CallbackHandler callbackHandler,
                               Session session,
                               Map options)
                        throws LoginException

Implementations may set-up their own state. E. g. a DataSource if it is authorized against an external System

Parameters:

callbackHandler - as passed by LoginContext

session - to security-workspace of Jackrabbit

options - options from Logini config

Throws:

LoginException - in case initializeaiton failes

isInitialized

protected boolean isInitialized()

Returns true if this module has been successfully initialized.

Returns:

true if this module has been successfully initialized.

See Also:

LoginModule.initialize(Subject, CallbackHandler, Map, Map)

login

public boolean login()
              throws LoginException

Method to authenticate a Subject (phase 1).

The login is devided into 3 Phases:

1) User-ID resolution
In a first step it is tried to resolve a User-ID for further validation. As for JCR the identification is marked with the Credentials interface, credentials are accessed in this phase.
If no User-ID can be found, anonymous access is granted with the ID of the anonymous user (as defined in the security configuration). Anonymous access can be switched off removing the configuration entry.
This implementation uses two helper-methods, which allow for customization:

• getCredentials()
and
• getUserID(Credentials)

2) User-Principal resolution
In a second step it is tested, if the resolved User-ID belongs to a User known to the system, i.e. if the PrincipalProvider has a principal for the given ID and the principal can be found via PrincipalProvider.findPrincipals(String).
The provider implemenation can be set by the configuration option with the name principal_provider.class. If the option is missing, the system default prinvipal provider will be used.

3) Verfication
There are two cases, how the User-ID can be verfied: Either the login is the result of an impersonation request (see Session.impersonate(Credentials) or of a login to the Repository (Repository.login(Credentials)). The concrete implementation of the LoginModule is responsible for both impersonation and login:

• authenticate(Principal, Credentials)
• impersonate(Principal, Credentials)

Under the following conditions, the login process is aborted and the module is marked to be ignored:

• No User-ID could be resolve, and anyonymous access is switched off
• No Principal is found for the User-ID resolved

Under the follwoing conditions, the login process is marked to be invalid by throwing an LoginException:

• It is an impersonation request, but the impersonator is not allowed to impersonate to the requested User-ID
• The user tries to login, but the Credentials can not be verified.

The LoginModule keeps the Credentials and the Principal as instance fields, to mark that login has been successfull.

Specified by:

login in interface LoginModule

Returns:

true if the authentication succeeded, or false if this LoginModule should be ignored.

Throws:

LoginException - if the authentication fails

See Also:

LoginModule.login(), getCredentials(), getUserID(Credentials), getImpersonatorSubject(Credentials)

commit

public boolean commit()
               throws LoginException

Method to commit the authentication process (phase 2).

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

If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the login method), then this method associates relevant Principals and Credentials with the Subject located in the LoginModule. If this LoginModule's own authentication attempted failed, then this method removes/destroys any state that was originally saved.

The login is considers as succeeded if the credentials field is set. If there is no principal set the login is considered as ignored.

The implementation stores the principal associated to the UserID and all the Groups it is member of. PrincipalManager.getGroupMembership(Principal) An instance of (#link SimpleCredentials} containing only the UserID used to login is set to the Subject's public Credentials.

Specified by:

commit in interface LoginModule

Returns:

true if this method succeeded, or false if this LoginModule should be ignored.

Throws:

LoginException - if the commit fails

See Also:

LoginModule.commit(), login()

abort

public boolean abort()
              throws LoginException

Method to abort the authentication process (phase 2).

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

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

Specified by:

abort in interface LoginModule

Returns:

true if this method succeeded, or false if this LoginModule should be ignored.

Throws:

LoginException - if the abort fails

logout

public boolean logout()
               throws LoginException

Method which logs out a Subject.

An implementation of this method might remove/destroy a Subject's Principals and Credentials.

Specified by:

logout in interface LoginModule

Returns:

true if this method succeeded, or false if this LoginModule should be ignored.

Throws:

LoginException - if the logout fails

authenticate

protected boolean authenticate(Principal principal,
                               Credentials credentials)
                        throws RepositoryException,
                               FailedLoginException

Parameters:

principal -

credentials -

Returns:

true if Credentails authenticate, false if no Authentication can handle the given Credentials

Throws:

FailedLoginException - if the authentication failed.

RepositoryException

See Also:

getAuthentication(java.security.Principal, javax.jcr.Credentials), authenticate(java.security.Principal, javax.jcr.Credentials)

isImpersonation

protected boolean isImpersonation(Credentials credentials)

Test if the current request is an Impersonation attempt. The default implementation returns true if an subject for the impersonation can be retrieved.

Parameters:

credentials - potentially containing impersonation data

Returns:

true if this is an impersonation attempt

See Also:

getImpersonatorSubject(Credentials)

impersonate

protected abstract boolean impersonate(Principal principal,
                                       Credentials credentials)
                                throws RepositoryException,
                                       LoginException

Handles the impersonation of given Credentials.

Current implementation takes User for the given Principal and delegates the check to Impersonation.allows(javax.security.auth.Subject) }

Parameters:

principal -

credentials -

Returns:

false, if there is no User to impersonate, true if impersonation is allowed

Throws:

RepositoryException

FailedLoginException - if credentials don't allow to impersonate to principal

LoginException

getAuthentication

protected abstract Authentication getAuthentication(Principal principal,
                                                    Credentials creds)
                                             throws RepositoryException

Parameters:

principal -

creds -

Returns:

Throws:

RepositoryException

getImpersonatorSubject

protected Subject getImpersonatorSubject(Credentials credentials)

Method tries to acquire an Impersonator in the follwing order:

• Try to access it from the Credentials via SimpleCredentials.getAttribute(String)
• Ask CallbackHandler for Impersonator with use of ImpersonationCallback.

Parameters:

credentials - which, may contain an impersonation Subject

Returns:

impersonation subject or null if non contained

See Also:

login(), impersonate(java.security.Principal, javax.jcr.Credentials)

getCredentials

protected Credentials getCredentials()

Method tries to resolve the Credentials used for login. It takes authentication-extension of an already authenticated Subject into accout.

Therefore the credentials are searchred as follows:

1. Test if the shared state contains credentials.
2. Ask CallbackHandler for Credentials with using a CredentialsCallback. Expects CredentialsCallback.getCredentials() to return an instance of Credentials.
3. Ask the Subject for its public SimpleCredentials see Subject.getPublicCredentials(Class), thus enabling to preauthenticate the Subject.

Returns:

Credentials or null if not found

See Also:

login()

getUserID

protected String getUserID(Credentials credentials)

Method supports tries to acquire a UserID in the follwing order:

1. If passed credentials are GuestCredentials the anonymous user id is returned.
2. Try to access it from the Credentials via SimpleCredentials.getUserID()
3. Ask CallbackHandler for User-ID with use of NameCallback.
4. Test if the 'sharedState' contains a login name.
5. Fallback: return the anonymous UserID.

Parameters:

credentials - which, may contain a User-ID

Returns:

The userId retrieved from the credentials or by any other means described above.

See Also:

login()

isAnonymous

protected boolean isAnonymous(Credentials credentials)

Indicate if the given Credentials are considered to be anonymous.

Parameters:

credentials -

Returns:

true if is anonymous

getPrincipal

protected abstract Principal getPrincipal(Credentials credentials)

Authentication process associates a Principal to Credentials
This method resolves the Principal for the given Credentials. If no valid Principal can be determined, the LoginModule should be ignored.

Parameters:

credentials -

Returns:

the principal associated with the given credentials or null.

getPrincipals

protected Set getPrincipals()

Returns:

a Collection of principals that contains the current user principal and all groups it is member of.

getAdminId

public String getAdminId()

Returns the admin user id.

Returns:

admin user id

setAdminId

public void setAdminId(String adminId)

Sets the administrator's user id.

Parameters:

adminId - the administrator's user id.

getAnonymousId

public String getAnonymousId()

Returns the anonymous user id.

Returns:

anonymous user id

setAnonymousId

public void setAnonymousId(String anonymousId)

Sets the anonymous user id.

Parameters:

anonymousId - anonymous user id

getPrincipalProvider

public String getPrincipalProvider()

Returns the configured name of the principal provider class.

Returns:

name of the principal provider class.

setPrincipalProvider

public void setPrincipalProvider(String principalProvider)

Sets the configured name of the principal provider class

Parameters:

principalProvider - Name of the principal provider class.