org.owasp.esapi
Interface Authenticator

All Known Implementing Classes:

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.

Once 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() Clear the current user.
User	createUser(java.lang.String accountName, java.lang.String password1, java.lang.String password2) Creates the user.
boolean	exists(java.lang.String accountName) Determine if the account already 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(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(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Authenticates the user's credentials from the HttpServletRequest if necessary, creates a session if necessary, and sets the user as the current user.
void	logout() Logs out the current user.
void	removeUser(java.lang.String accountName) Removes the account.
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.
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) Ensures that the password meets site-specific complexity requirements.

Method Detail

clearCurrent

public void clearCurrent()

Clear the current user. This allows the thread to be reused safely.

login

public User login(javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws AuthenticationException

Authenticates the user's credentials from the HttpServletRequest if necessary, creates a session if necessary, and sets the user as the current user.

Parameters:

request - the current HTTP request

response - the response

Returns:

the user

Throws:

AuthenticationException - the authentication exception

verifyPassword

public boolean verifyPassword(User user,
                              java.lang.String password)

Verify that the supplied password matches the password for this user. 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

password - the password

Returns:

true if the password is correct for the specified user

logout

public void logout()

Logs out the current user.

createUser

public User createUser(java.lang.String accountName,
                       java.lang.String password1,
                       java.lang.String password2)
                throws AuthenticationException

Creates the user.

Parameters:

accountName - the account name

password1 - the password

password2 - copy of the password

Returns:

the new User object

Throws:

AuthenticationException - the authentication exception FIXME RD: We should throw a specific exception if the account name already exists Also, should callers synchronize while checking exists() and calling createUser()?

generateStrongPassword

public java.lang.String generateStrongPassword()

Generate a strong password.

Returns:

the string

generateStrongPassword

public java.lang.String generateStrongPassword(User user,
                                               java.lang.String oldPassword)

Generate strong password that takes into account the user's information and old password.

Parameters:

oldPassword - the old password

user - the user

Returns:

the new password

changePassword

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

public User getUser(java.lang.String accountName)

Returns the User matching the provided accountName.

Parameters:

accountName - the account name

Returns:

the matching User object, or null if no match exists

getUserNames

public java.util.Set getUserNames()

Gets a collection containing all the existing user names.

Returns:

the user names

getCurrentUser

public User getCurrentUser()

Returns the currently logged in User.

Returns:

the matching User object, or the Anonymous user if no match exists

setCurrentUser

public void setCurrentUser(User user)

Sets the currently logged in User.

Parameters:

user - the current user

hashPassword

public 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

accountName - the account name

Returns:

the hashed password

Throws:

EncryptionException

removeUser

public void removeUser(java.lang.String accountName)
                throws AuthenticationException

Removes the account.

Parameters:

accountName - the account name

Throws:

AuthenticationException - the authentication exception

verifyAccountNameStrength

public void verifyAccountNameStrength(java.lang.String accountName)
                               throws AuthenticationException

Ensures that the account name passes site-specific complexity requirements.

Parameters:

accountName - the account name

Returns:

true, if successful

Throws:

AuthenticationException - the authentication exception

verifyPasswordStrength

public void verifyPasswordStrength(java.lang.String oldPassword,
                                   java.lang.String newPassword)
                            throws AuthenticationException

Ensures that the password meets site-specific complexity requirements. 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 this list of old credentials stored by ESAPI are all hashed.

Parameters:

oldPassword - the old password

newPassword - the new password

Returns:

true, if successful

Throws:

AuthenticationException - the authentication exception

exists

public boolean exists(java.lang.String accountName)

Determine if the account already exists.

Parameters:

accountName - the account name

Returns:

true, if the account exists