org.dspace.authenticate

Interface AuthenticationMethod

All Known Implementing Classes:

IPAuthentication, LDAPAuthentication, PasswordAuthentication, ShibAuthentication, X509Authentication

public interface AuthenticationMethod

Implement this interface to participate in the stackable authentication mechanism. See the AuthenticationManager class for details about configuring authentication handlers.

Each authentication method provides a way to map "credentials" supplied by the client into a DSpace e-person. "Authentication" is when the credentials are compared against some sort of registry or other test of authenticity.

The DSpace instance may configure many authentication methods, in a "stack". The same credentials are passed to each method in turn until one accepts them, so each method need only attempt to interpret and validate the credentials and fail gracefully if they are not appropriate for it. The next method in the stack is then called.

Version:

$Revision$

Author:

Larry Stone

See Also:

AuthenticationManager

Field Summary

Fields

Modifier and Type	Field and Description
static int	BAD_ARGS User or password is not appropriate for this method.
static int	BAD_CREDENTIALS User exists, but credentials (e.g. passwd) don't match.
static int	CERT_REQUIRED Not allowed to login this way without X.509 certificate.
static int	NO_SUCH_USER User not found using this method.
static int	SUCCESS Authenticated OK, EPerson has been set.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	allowSetPassword(Context context, javax.servlet.http.HttpServletRequest request, java.lang.String username) Should (or can) we allow the user to change their password.
int	authenticate(Context context, java.lang.String username, java.lang.String password, java.lang.String realm, javax.servlet.http.HttpServletRequest request) Authenticate the given or implicit credentials.
boolean	canSelfRegister(Context context, javax.servlet.http.HttpServletRequest request, java.lang.String username) Predicate, whether to allow new EPerson to be created.
int[]	getSpecialGroups(Context context, javax.servlet.http.HttpServletRequest request) Get list of extra groups that user implicitly belongs to.
void	initEPerson(Context context, javax.servlet.http.HttpServletRequest request, EPerson eperson) Initialize a new EPerson record for a self-registered new user.
boolean	isImplicit() Predicate, is this an implicit authentication method.
java.lang.String	loginPageTitle(Context context) Get title of login page to which to redirect.
java.lang.String	loginPageURL(Context context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Get login page to which to redirect.

Field Detail

SUCCESS

static final int SUCCESS

Authenticated OK, EPerson has been set.

See Also:

Constant Field Values

BAD_CREDENTIALS

static final int BAD_CREDENTIALS

User exists, but credentials (e.g. passwd) don't match.

See Also:

Constant Field Values

CERT_REQUIRED

static final int CERT_REQUIRED

Not allowed to login this way without X.509 certificate.

See Also:

Constant Field Values

NO_SUCH_USER

static final int NO_SUCH_USER

User not found using this method.

See Also:

Constant Field Values

BAD_ARGS

static final int BAD_ARGS

User or password is not appropriate for this method.

See Also:

Constant Field Values

Method Detail

canSelfRegister

boolean canSelfRegister(Context context,
                      javax.servlet.http.HttpServletRequest request,
                      java.lang.String username)
                        throws java.sql.SQLException

Predicate, whether to allow new EPerson to be created. The answer determines whether a new user is created when the credentials describe a valid entity but there is no corresponding EPerson in DSpace yet. The EPerson is only created if authentication succeeds.

Parameters:

context - DSpace context

request - HTTP request, in case it's needed. May be null.

username - Username, if available. May be null.

Returns:

true if new ePerson should be created.

Throws:

java.sql.SQLException

initEPerson

void initEPerson(Context context,
               javax.servlet.http.HttpServletRequest request,
               EPerson eperson)
                 throws java.sql.SQLException

Initialize a new EPerson record for a self-registered new user. Set any data in the EPerson that is specific to this authentication method.

Parameters:

context - DSpace context

request - HTTP request, in case it's needed. May be null.

eperson - newly created EPerson record - email + information from the registration form will have been filled out.

Throws:

java.sql.SQLException

allowSetPassword

boolean allowSetPassword(Context context,
                       javax.servlet.http.HttpServletRequest request,
                       java.lang.String username)
                         throws java.sql.SQLException

Should (or can) we allow the user to change their password. Note that this means the password stored in the EPerson record, so if any method in the stack returns true, the user is allowed to change it.

Parameters:

context - DSpace context

request - HTTP request, in case it's needed. May be null.

username - Username, if available. May be null.

Returns:

true if this method allows user to change ePerson password.

Throws:

java.sql.SQLException

isImplicit

boolean isImplicit()

Predicate, is this an implicit authentication method. An implicit method gets credentials from the environment (such as an HTTP request or even Java system properties) rather than the explicit username and password. For example, a method that reads the X.509 certificates in an HTTPS request is implicit.

Returns:

true if this method uses implicit authentication.

getSpecialGroups

int[] getSpecialGroups(Context context,
                     javax.servlet.http.HttpServletRequest request)
                       throws java.sql.SQLException

Get list of extra groups that user implicitly belongs to. Note that this method will be invoked regardless of the authentication status of the user (logged-in or not) e.g. a group that depends on the client network-address.

It might make sense to implement this method by itself in a separate authentication method that just adds special groups, if the code doesn't belong with any existing auth method. The stackable authentication system was designed expressly to separate functions into "stacked" methods to keep your site-specific code modular and tidy.

Parameters:

context - A valid DSpace context.

request - The request that started this operation, or null if not applicable.

Returns:

array of EPerson-group IDs, possibly 0-length, but never null.

Throws:

java.sql.SQLException

authenticate

int authenticate(Context context,
               java.lang.String username,
               java.lang.String password,
               java.lang.String realm,
               javax.servlet.http.HttpServletRequest request)
                 throws java.sql.SQLException

Authenticate the given or implicit credentials. This is the heart of the authentication method: test the credentials for authenticity, and if accepted, attempt to match (or optionally, create) an EPerson. If an EPerson is found it is set in the Context that was passed.

Parameters:

context - DSpace context, will be modified (ePerson set) upon success.

username - Username (or email address) when method is explicit. Use null for implicit method.

password - Password for explicit auth, or null for implicit method.

realm - Realm is an extra parameter used by some authentication methods, leave null if not applicable.

request - The HTTP request that started this operation, or null if not applicable.

Returns:

One of: SUCCESS, BAD_CREDENTIALS, CERT_REQUIRED, NO_SUCH_USER, BAD_ARGS

Meaning:
SUCCESS - authenticated OK.
BAD_CREDENTIALS - user exists, but credentials (e.g. passwd) don't match
CERT_REQUIRED - not allowed to login this way without X.509 cert.
NO_SUCH_USER - user not found using this method.
BAD_ARGS - user/pw not appropriate for this method

Throws:

java.sql.SQLException

loginPageURL

java.lang.String loginPageURL(Context context,
                            javax.servlet.http.HttpServletRequest request,
                            javax.servlet.http.HttpServletResponse response)

Get login page to which to redirect. Returns URL (as string) to which to redirect to obtain credentials (either password prompt or e.g. HTTPS port for client cert.); null means no redirect.

Parameters:

context - DSpace context, will be modified (ePerson set) upon success.

request - The HTTP request that started this operation, or null if not applicable.

response - The HTTP response from the servlet method.

Returns:

fully-qualified URL or null

loginPageTitle

java.lang.String loginPageTitle(Context context)

Get title of login page to which to redirect. Returns a message key that gets translated into the title or label for "login page" (or null, if not implemented) This title may be used to identify the link to the login page in a selection menu, when there are multiple ways to login.

Parameters:

context - DSpace context, will be modified (ePerson set) upon success.

Returns:

title text.