org.dspace.authenticate

Class X509Authentication

java.lang.Object

org.dspace.authenticate.X509Authentication

All Implemented Interfaces:

AuthenticationMethod

public class X509Authentication
extends Object
implements AuthenticationMethod

Implicit authentication method that gets credentials from the X.509 client certificate supplied by the HTTPS client when connecting to this server. The email address in that certificate is taken as the authenticated user name with no further checking, so be sure your HTTP server (e.g. Tomcat) is configured correctly to accept only client certificates it can validate.

See the AuthenticationMethod interface for more details.

Configuration:

   x509.keystore.path =
 
 path to Java keystore file
 
   keystore.password =
 
 password to access the keystore
 
   ca.cert =
 
 path to certificate file for CA whose client certs to accept.
 
   autoregister =
 
 "true" if E-Person is created automatically for unknown new users.
 
   groups =
 
 comma-delimited list of special groups to add user to if authenticated.
 
   emaildomain =
 
 email address domain (after the 'at' symbol) to match before allowing 
 membership in special groups.
 
 

Only one of the "keystore.path" or "ca.cert" options is required. If you supply a keystore, then all of the "trusted" certificates in the keystore represent CAs whose client certificates will be accepted. The ca.cert option only allows a single CA to be named.

You can configure both a keystore and a CA cert, and both will be used.

The autoregister configuration parameter determines what the canSelfRegister() method returns. It also allows an EPerson record to be created automatically when the presented certificate is acceptable but there is no corresponding EPerson.

Version:

$Revision$

Author:

Larry Stone

Field Summary

Fields inherited from interface org.dspace.authenticate.AuthenticationMethod

BAD_ARGS, BAD_CREDENTIALS, CERT_REQUIRED, NO_SUCH_USER, SUCCESS

Constructor Summary

Constructors

Constructor and Description
X509Authentication()

Method Summary

Methods

Modifier and Type	Method and Description
boolean	allowSetPassword(Context context, javax.servlet.http.HttpServletRequest request, String username) We don't use EPerson password so there is no reason to change it.
int	authenticate(Context context, String username, String password, String realm, javax.servlet.http.HttpServletRequest request) X509 certificate authentication.
boolean	canSelfRegister(Context context, javax.servlet.http.HttpServletRequest request, String username) Predicate, can new user automatically create EPerson.
int[]	getSpecialGroups(Context context, javax.servlet.http.HttpServletRequest request) Return special groups configured in dspace.cfg for X509 certificate authentication.
void	initEPerson(Context context, javax.servlet.http.HttpServletRequest request, EPerson eperson) Nothing extra to initialize.
boolean	isImplicit() Returns true, this is an implicit method.
String	loginPageTitle(Context context) Returns message key for title of the "login" page, to use in a menu showing the choice of multiple login methods.
String	loginPageURL(Context context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Returns URL of password-login servlet.

Methods inherited from class java.lang.Object

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

Constructor Detail

X509Authentication

public X509Authentication()

Method Detail

canSelfRegister

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

Predicate, can new user automatically create EPerson. Checks configuration value. You'll probably want this to be true to take advantage of a Web certificate infrastructure with many more users than are already known by DSpace.

Specified by:

canSelfRegister in interface AuthenticationMethod

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:

SQLException

initEPerson

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

Nothing extra to initialize.

Specified by:

initEPerson in interface AuthenticationMethod

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:

SQLException

allowSetPassword

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

We don't use EPerson password so there is no reason to change it.

Specified by:

allowSetPassword in interface AuthenticationMethod

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:

SQLException

isImplicit

public boolean isImplicit()

Returns true, this is an implicit method.

Specified by:

isImplicit in interface AuthenticationMethod

Returns:

true if this method uses implicit authentication.

getSpecialGroups

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

Return special groups configured in dspace.cfg for X509 certificate authentication.

Specified by:

getSpecialGroups in interface AuthenticationMethod

Parameters:

context -

request - object potentially containing the cert

Returns:

An int array of group IDs

Throws:

SQLException

authenticate

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

X509 certificate authentication. The client certificate is obtained from the ServletRequest object.

• If the certificate is valid, and corresponds to an existing EPerson, and the user is allowed to login, return success.
• If the user is matched but is not allowed to login, it fails.
• If the certificate is valid, but there is no corresponding EPerson, the "authentication.x509.autoregister" configuration parameter is checked (via canSelfRegister())
  • If it's true, a new EPerson record is created for the certificate, and the result is success.
  • If it's false, return that the user was unknown.

Specified by:

authenticate in interface AuthenticationMethod

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, NO_SUCH_USER, BAD_ARGS

Throws:

SQLException

loginPageURL

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

Returns URL of password-login servlet.

Specified by:

loginPageURL in interface AuthenticationMethod

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

loginPageTitle

public String loginPageTitle(Context context)

Returns message key for title of the "login" page, to use in a menu showing the choice of multiple login methods.

Specified by:

loginPageTitle in interface AuthenticationMethod

Parameters:

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

Returns:

Message key to look up in i18n message catalog.