Package org.dspace.authenticate

Interface AuthenticationMethod

All Known Implementing Classes:
IPAuthentication, LDAPAuthentication, OidcAuthentication, OidcAuthenticationBean, OrcidAuthentication, OrcidAuthenticationBean, PasswordAuthentication, SamlAuthentication, 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:

  • Field Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    allowSetPassword(Context context, jakarta.servlet.http.HttpServletRequest request, String username)
    Should (or can) we allow the user to change their password.
    default boolean
    areSpecialGroupsApplicable(Context context, jakarta.servlet.http.HttpServletRequest request)
    Returns true if the special groups returned by getSpecialGroups(Context, HttpServletRequest) should be implicitly be added to the groups related to the current user.
    int
    authenticate(Context context, String username, String password, String realm, jakarta.servlet.http.HttpServletRequest request)
    Authenticate the given or implicit credentials.
    boolean
    canChangePassword(Context context, EPerson ePerson, String currentPassword)
    Check if the given current password is valid to change the password of the given ePerson
    boolean
    canSelfRegister(Context context, jakarta.servlet.http.HttpServletRequest request, String username)
    Predicate, whether to allow new EPerson to be created.
    String
    getName()
    Returns a short name that uniquely identifies this authentication method
    List<Group>
    getSpecialGroups(Context context, jakarta.servlet.http.HttpServletRequest request)
    Get list of extra groups that user implicitly belongs to.
    void
    initEPerson(Context context, jakarta.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.
    boolean
    isUsed(Context context, jakarta.servlet.http.HttpServletRequest request)
    Get whether the authentication method is being used.
    String
    loginPageURL(Context context, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
    Get an external login page to which to redirect.

  • Field Details

    • SUCCESS

      static final int SUCCESS
      Authenticated OK, EPerson has been set.
      See Also:

    • BAD_CREDENTIALS

      static final int BAD_CREDENTIALS
      User exists, but credentials (e.g. passwd) don't match.
      See Also:

    • CERT_REQUIRED

      static final int CERT_REQUIRED
      Not allowed to login this way without X.509 certificate.
      See Also:

    • NO_SUCH_USER

      static final int NO_SUCH_USER
      User not found using this method.
      See Also:

    • BAD_ARGS

      static final int BAD_ARGS
      User or password is not appropriate for this method.
      See Also:

  • Method Details

    • canSelfRegister

      boolean canSelfRegister(Context context, jakarta.servlet.http.HttpServletRequest request, String username) throws 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:
      SQLException - if database error

    • initEPerson

      void initEPerson(Context context, jakarta.servlet.http.HttpServletRequest request, EPerson eperson) throws 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:
      SQLException - if database error

    • allowSetPassword

      boolean allowSetPassword(Context context, jakarta.servlet.http.HttpServletRequest request, String username) throws 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:
      SQLException - if database error

    • 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

      List<Group> getSpecialGroups(Context context, jakarta.servlet.http.HttpServletRequest request) throws 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:
      SQLException - if database error

    • areSpecialGroupsApplicable

      default boolean areSpecialGroupsApplicable(Context context, jakarta.servlet.http.HttpServletRequest request)
      Returns true if the special groups returned by getSpecialGroups(Context, HttpServletRequest) should be implicitly be added to the groups related to the current user. By default this is true if the authentication method is the actual authentication mechanism used by the user.
      Parameters:
      context - A valid DSpace context.
      request - The request that started this operation, or null if not applicable.
      Returns:
      true is the special groups must be considered, false otherwise

    • authenticate

      int authenticate(Context context, String username, String password, String realm, jakarta.servlet.http.HttpServletRequest request) throws 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:
      SQLException - if database error

    • loginPageURL

      String loginPageURL(Context context, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
      Get an external 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. Note: Starting with DSpace 7, session logins will be managed through the REST API. Therefore, only authn providers with external login pages (such as Shibboleth) should return a login page.
      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

    • getName

      String getName()
      Returns a short name that uniquely identifies this authentication method
      Returns:
      The authentication method name

    • isUsed

      boolean isUsed(Context context, jakarta.servlet.http.HttpServletRequest request)
      Get whether the authentication method is being used.
      Parameters:
      context - The DSpace context
      request - The current request
      Returns:
      whether the authentication method is being used.

    • canChangePassword

      boolean canChangePassword(Context context, EPerson ePerson, String currentPassword)
      Check if the given current password is valid to change the password of the given ePerson
      Parameters:
      context - The DSpace context
      ePerson - the ePerson related to the password change
      currentPassword - The current password to check
      Returns:
      true if the provided password matches with current password