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 successful 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 behavior for either method.

See Also:

LoginModule

Field Summary

protected String	adminId
protected String	anonymousId
protected CallbackHandler	callbackHandler
protected SimpleCredentials	credentials
protected Principal	principal
protected PrincipalProvider	principalProvider
protected Map	sharedState
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) Retrieve the Authentication.
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 String	getPreAuthAttributeName() The name of the credentials attribute providing a hint that the credentials should be taken as is and the user requesting access has already been authenticated outside of this LoginModule.
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<Principal>	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<String,?> sharedState, Map<String,?> options) Initialize this LoginModule and sets the following fields for later usage: PrincipalProvider for user-Principal resolution.
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.
protected boolean	isPreAuthenticated(Credentials creds) Returns true if the credentials should be considered as pre-authenticated and a password check is not required.
boolean	login() Method to authenticate a Subject (phase 1).
boolean	logout()
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
protected boolean	supportsCredentials(Credentials creds) Return a flag indicating whether the credentials are supported by this login module.

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

callbackHandler

protected CallbackHandler callbackHandler

principal

protected Principal principal

credentials

protected SimpleCredentials credentials

subject

protected Subject subject

principalProvider

protected PrincipalProvider principalProvider

sharedState

protected Map sharedState

Constructor Detail

AbstractLoginModule

public AbstractLoginModule()

Method Detail

initialize

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

Initialize this LoginModule and sets the following fields for later usage:

• 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.

Parameters:

callbackHandler - as passed by LoginContext

session - to security-workspace of Jackrabbit

options - options from Logini config

Throws:

LoginException - in case initialization 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 implementation can be set by the LoginModule configuration. If the option is missing, the system default principal provider will be used.

3) Verification
There are four cases, how the User-ID can be verified: The login is anonymous, preauthenticated or 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 all four cases:

• isAnonymous(Credentials)
• isPreAuthenticated(Credentials)
• 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 anonymous access is switched off
• No Principal is found for the User-ID resolved

Under the following 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 successful.

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 considered as succeeded if there is a principal set.

The implementation stores the principal associated to the UserID and all the Groups it is member of with the Subject and in addition adds an instance of (#link SimpleCredentials} 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()

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

See Also:

LoginModule.abort()

logout

public boolean logout()
               throws LoginException

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

See Also:

LoginModule.logout()

authenticate

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

Parameters:

principal - Principal used to retrieve the Authentication object.

credentials - Credentials used for the authentication.

Returns:

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

Throws:

FailedLoginException - if the authentication failed.

RepositoryException - If another error occurs.

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.

Parameters:

principal - Principal to impersonate.

credentials - Credentials used to create the impersonation subject.

Returns:

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

Throws:

LoginException - If credentials don't allow to impersonate to principal.

RepositoryException - If another error occurs.

getAuthentication

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

Retrieve the Authentication.

Parameters:

principal - A principal.

creds - The Credentials used for the login.

Returns:

Authentication object for the given principal / credentials.

Throws:

RepositoryException - If an error occurs.

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 retrieved 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()

supportsCredentials

protected boolean supportsCredentials(Credentials creds)

Return a flag indicating whether the credentials are supported by this login module. Default implementation supports SimpleCredentials and GuestCredentials.

Parameters:

creds - credentials

Returns:

true if the credentials are supported; false otherwise

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 - The Credentials to be tested.

Returns:

true if is anonymous; false otherwise.

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 - Credentials used for to login.

Returns:

the principal associated with the given credentials or null.

getPrincipals

protected Set<Principal> 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.

getPreAuthAttributeName

protected final String getPreAuthAttributeName()

The name of the credentials attribute providing a hint that the credentials should be taken as is and the user requesting access has already been authenticated outside of this LoginModule.

This name is configured as the value of the LoginModule configuration parameter trust_credentials_attribute. If the configuration parameter is missing (or empty) the name is not set and this method returns null.

See Also:

isPreAuthenticated(Credentials)

isPreAuthenticated

protected boolean isPreAuthenticated(Credentials creds)

Returns true if the credentials should be considered as pre-authenticated and a password check is not required.

This base class implementation returns true if the creds object is a SimpleCredentials instance and the configured trusted credentials property is set to a non-null value in the credentials attributes.

Extensions of this class may overwrite this method to apply more or different checks to the credentials.

Parameters:

creds - The Credentials to check

See Also:

getPreAuthAttributeName()