org.owasp.esapi
Interface Authenticator

All Known Implementing Classes:
AbstractAuthenticator, FileBasedAuthenticator

public interface Authenticator

The Authenticator interface defines a set of methods for generating and handling account credentials and session identifiers. The goal of this interface is to encourage developers to protect credentials from disclosure to the maximum extent possible.

One possible implementation relies on the use of a thread local variable to store the current user's identity. The application is responsible for calling setCurrentUser() as soon as possible after each HTTP request is received. The value of getCurrentUser() is used in several other places in this API. This eliminates the need to pass a user object to methods throughout the library. For example, all of the logging, access control, and exception calls need access to the currently logged in user.

The goal is to minimize the responsibility of the developer for authentication. In this example, the user simply calls authenticate with the current request and the name of the parameters containing the username and password. The implementation should verify the password if necessary, create a session if necessary, and set the user as the current user.

 public void doPost(ServletRequest request, ServletResponse response) {
 try {
 User user = ESAPI.authenticator().login(request, response);
 // continue with authenticated user
 } catch (AuthenticationException e) {
 // handle failed authentication (it's already been logged)
 }
 

Since:
June 1, 2007
Author:
Jeff Williams (jeff.williams .at. aspectsecurity.com) Aspect Security

Method Summary
 void changePassword(User user, java.lang.String currentPassword, java.lang.String newPassword, java.lang.String newPassword2)
          Changes the password for the specified user.
 void clearCurrent()
          Clears the current User.
 User createUser(java.lang.String accountName, java.lang.String password1, java.lang.String password2)
          Creates a new User with the information provided.
 boolean exists(java.lang.String accountName)
          Determine if the account exists.
 java.lang.String generateStrongPassword()
          Generate a strong password.
 java.lang.String generateStrongPassword(User user, java.lang.String oldPassword)
          Generate strong password that takes into account the user's information and old password.
 User getCurrentUser()
          Returns the currently logged in User.
 User getUser(long accountId)
          Returns the User matching the provided accountId.
 User getUser(java.lang.String accountName)
          Returns the User matching the provided accountName.
 java.util.Set getUserNames()
          Gets a collection containing all the existing user names.
 java.lang.String hashPassword(java.lang.String password, java.lang.String accountName)
          Returns a string representation of the hashed password, using the accountName as the salt.
 User login()
          Calls login with the *current* request and response.
 User login(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          This method should be called for every HTTP request, to login the current user either from the session of HTTP request.
 void logout()
          Logs out the current user.
 void removeUser(java.lang.String accountName)
          Removes the account of the specified accountName.
 void setCurrentUser(User user)
          Sets the currently logged in User.
 void verifyAccountNameStrength(java.lang.String accountName)
          Ensures that the account name passes site-specific complexity requirements, like minimum length.
 boolean verifyPassword(User user, java.lang.String password)
          Verify that the supplied password matches the password for this user.
 void verifyPasswordStrength(java.lang.String oldPassword, java.lang.String newPassword, User user)
          Ensures that the password meets site-specific complexity requirements, like length or number of character sets.
 

Method Detail

clearCurrent

void clearCurrent()
Clears the current User. This allows the thread to be reused safely. This clears all threadlocal variables from the thread. This should ONLY be called after all possible ESAPI operations have concluded. If you clear too early, many calls will fail, including logging, which requires the user identity.


login

User login()
           throws AuthenticationException
Calls login with the *current* request and response.

Returns:
Authenticated User if login is successful.
Throws:
AuthenticationException
See Also:
HTTPUtilities.setCurrentHTTP(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

login

User login(javax.servlet.http.HttpServletRequest request,
           javax.servlet.http.HttpServletResponse response)
           throws AuthenticationException
This method should be called for every HTTP request, to login the current user either from the session of HTTP request. This method will set the current user so that getCurrentUser() will work properly. Authenticates the user's credentials from the HttpServletRequest if necessary, creates a session if necessary, and sets the user as the current user. Specification: The implementation should do the following: 1) Check if the User is already stored in the session a. If so, check that session absolute and inactivity timeout have not expired b. Step 2 may not be required if 1a has been satisfied 2) Verify User credentials a. It is recommended that you use loginWithUsernameAndPassword(HttpServletRequest, HttpServletResponse) to verify credentials 3) Set the last host of the User (ex. user.setLastHostAddress(address) ) 4) Verify that the request is secure (ex. over SSL) 5) Verify the User account is allowed to be logged in a. Verify the User is not disabled, expired or locked 6) Assign User to session variable

Parameters:
request - the current HTTP request
response - the HTTP response
Returns:
the User
Throws:
AuthenticationException - if the credentials are not verified, or if the account is disabled, locked, expired, or timed out

verifyPassword

boolean verifyPassword(User user,
                       java.lang.String password)
Verify that the supplied password matches the password for this user. Password should be stored as a hash. It is recommended you use the hashPassword(password, accountName) method in this class. This method is typically used for "reauthentication" for the most sensitive functions, such as transactions, changing email address, and changing other account information.

Parameters:
user - the user who requires verification
password - the hashed user-supplied password
Returns:
true, if the password is correct for the specified user

logout

void logout()
Logs out the current user. This is usually done by calling User.logout on the current User.


createUser

User createUser(java.lang.String accountName,
                java.lang.String password1,
                java.lang.String password2)
                throws AuthenticationException
Creates a new User with the information provided. Implementations should check accountName and password for proper format and strength against brute force attacks ( verifyAccountNameStrength(String), verifyPasswordStrength(String, String) ). Two copies of the new password are required to encourage user interface designers to include a "re-type password" field in their forms. Implementations should verify that both are the same.

Parameters:
accountName - the account name of the new user
password1 - the password of the new user
password2 - the password of the new user. This field is to encourage user interface designers to include two password fields in their forms.
Returns:
the User that has been created
Throws:
AuthenticationException - if user creation fails due to any of the qualifications listed in this method's description

generateStrongPassword

java.lang.String generateStrongPassword()
Generate a strong password. Implementations should use a large character set that does not include confusing characters, such as i I 1 l 0 o and O. There are many algorithms to generate strong memorable passwords that have been studied in the past.

Returns:
a password with strong password strength

generateStrongPassword

java.lang.String generateStrongPassword(User user,
                                        java.lang.String oldPassword)
Generate strong password that takes into account the user's information and old password. Implementations should verify that the new password does not include information such as the username, fragments of the old password, and other information that could be used to weaken the strength of the password.

Parameters:
user - the user whose information to use when generating password
oldPassword - the old password to use when verifying strength of new password. The new password may be checked for fragments of oldPassword.
Returns:
a password with strong password strength

changePassword

void changePassword(User user,
                    java.lang.String currentPassword,
                    java.lang.String newPassword,
                    java.lang.String newPassword2)
                    throws AuthenticationException
Changes the password for the specified user. This requires the current password, as well as the password to replace it with. The new password should be checked against old hashes to be sure the new password does not closely resemble or equal any recent passwords for that User. Password strength should also be verified. This new password must be repeated to ensure that the user has typed it in correctly.

Parameters:
user - the user to change the password for
currentPassword - the current password for the specified user
newPassword - the new password to use
newPassword2 - a verification copy of the new password
Throws:
AuthenticationException - if any errors occur

getUser

User getUser(long accountId)
Returns the User matching the provided accountId. If the accoundId is not found, an Anonymous User or null may be returned.

Parameters:
accountId - the account id
Returns:
the matching User object, or the Anonymous User if no match exists

getUser

User getUser(java.lang.String accountName)
Returns the User matching the provided accountName. If the accoundId is not found, an Anonymous User or null may be returned.

Parameters:
accountName - the account name
Returns:
the matching User object, or the Anonymous User if no match exists

getUserNames

java.util.Set getUserNames()
Gets a collection containing all the existing user names.

Returns:
a set of all user names

getCurrentUser

User getCurrentUser()
Returns the currently logged in User.

Returns:
the matching User object, or the Anonymous User if no match exists

setCurrentUser

void setCurrentUser(User user)
Sets the currently logged in User.

Parameters:
user - the user to set as the current user

hashPassword

java.lang.String hashPassword(java.lang.String password,
                              java.lang.String accountName)
                              throws EncryptionException
Returns a string representation of the hashed password, using the accountName as the salt. The salt helps to prevent against "rainbow" table attacks where the attacker pre-calculates hashes for known strings. This method specifies the use of the user's account name as the "salt" value. The Encryptor.hash method can be used if a different salt is required.

Parameters:
password - the password to hash
accountName - the account name to use as the salt
Returns:
the hashed password
Throws:
EncryptionException

removeUser

void removeUser(java.lang.String accountName)
                throws AuthenticationException
Removes the account of the specified accountName.

Parameters:
accountName - the account name to remove
Throws:
AuthenticationException - the authentication exception if user does not exist

verifyAccountNameStrength

void verifyAccountNameStrength(java.lang.String accountName)
                               throws AuthenticationException
Ensures that the account name passes site-specific complexity requirements, like minimum length.

Parameters:
accountName - the account name
Throws:
AuthenticationException - if account name does not meet complexity requirements

verifyPasswordStrength

void verifyPasswordStrength(java.lang.String oldPassword,
                            java.lang.String newPassword,
                            User user)
                            throws AuthenticationException
Ensures that the password meets site-specific complexity requirements, like length or number of character sets. This method takes the old password so that the algorithm can analyze the new password to see if it is too similar to the old password. Note that this has to be invoked when the user has entered the old password, as the list of old credentials stored by ESAPI is all hashed. Additionally, the user object is taken in order to verify the password and account name differ.

Parameters:
oldPassword - the old password
newPassword - the new password
user - the user
Throws:
AuthenticationException - if newPassword is too similar to oldPassword or if newPassword does not meet complexity requirements

exists

boolean exists(java.lang.String accountName)
Determine if the account exists.

Parameters:
accountName - the account name
Returns:
true, if the account exists


Copyright © 2011 The Open Web Application Security Project (OWASP). All Rights Reserved.