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

Modifier and Type	Method and Description
void	changePassword(User user, String currentPassword, String newPassword, String newPassword2) Changes the password for the specified user.
void	clearCurrent() Clears the current User.
User	createUser(String accountName, String password1, String password2) Creates a new User with the information provided.
boolean	exists(String accountName) Determine if the account exists.
String	generateStrongPassword() Generate a strong password.
String	generateStrongPassword(User user, 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(String accountName) Returns the User matching the provided accountName.
Set	getUserNames() Gets a collection containing all the existing user names.
String	hashPassword(String password, 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(String accountName) Removes the account of the specified accountName.
void	setCurrentUser(User user) Sets the currently logged in User.
void	verifyAccountNameStrength(String accountName) Ensures that the account name passes site-specific complexity requirements, like minimum length.
boolean	verifyPassword(User user, String password) Verify that the supplied password matches the password for this user.
void	verifyPasswordStrength(String oldPassword, 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,
                       String password)

Verify that the supplied password matches the password for this user. Password should be stored as a hash. By default, this method verifies password hashes created via the hashPassword(password, accountName) method in this class, however see WARNING the hashPassword method.

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

See Also:

hashPassword(String password, String accountName)

logout

void logout()

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

createUser

User createUser(String accountName,
                String password1,
                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.

WARNING: The implementation of this method as defined in the default reference implementation class, FileBasedAuthenticator, uses a password hash algorthim that is known to be weak. You are advised to replace the default reference implementation class with your own custom implementation that uses a stronger password hashing algorithm. See class comments in * FileBasedAuthenticator for further details.

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

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

String generateStrongPassword(User user,
                              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,
                    String currentPassword,
                    String newPassword,
                    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(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

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

String hashPassword(String password,
                    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.

WARNING: The implementation of this method as defined in the default reference implementation class, FileBasedAuthenticator, is know to be extremely weak. The reference implementation class was meant to be an example implementation and generally should be avoided and replaced with your own implementation. See class comments in FileBasedAuthenticator for further details.

Parameters:

password - the password to hash

accountName - the account name to use as the salt

Returns:

the hashed password

Throws:

EncryptionException

See Also:

FileBasedAuthenticator, the default reference implementation of this interface.

removeUser

void removeUser(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(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(String oldPassword,
                            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(String accountName)

Determine if the account exists.

Parameters:

accountName - the account name

Returns:

true, if the account exists