org.owasp.esapi.interfaces
Interface IAuthenticator

All Known Implementing Classes:

Authenticator

public interface IAuthenticator

The IAuthenticator 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 {
 ESAPI.authenticator().authenticate(request, response, "username","password");
 // 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	clearCurrent() Clear the current user, request, and response.
IUser	createUser(java.lang.String accountName, java.lang.String password1, java.lang.String password2) Creates the user.
boolean	exists(java.lang.String accountName) Verifies the account exists.
java.lang.String	generateStrongPassword() Generate a strong password.
java.lang.String	generateStrongPassword(java.lang.String oldPassword, IUser user) Generate strong password that takes into account the user's information and old password.
IUser	getCurrentUser() Returns the currently logged in User.
IUser	getUser(java.lang.String accountName) Returns the User matching the provided accountName.
java.util.Set	getUserNames() Gets the 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.
IUser	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(IUser user) Sets the currently logged in User.
void	verifyAccountNameStrength(java.lang.String accountName) Validate password strength.
void	verifyPasswordStrength(java.lang.String newPassword, java.lang.String oldPassword) Validate password strength.

Method Detail

clearCurrent

public void clearCurrent()

Clear the current user, request, and response. This allows the thread to be reused safely.

login

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

logout

public void logout()

Logs out the current user.

createUser

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

generateStrongPassword

public java.lang.String generateStrongPassword()

Generate a strong password.

Returns:

the string

generateStrongPassword

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

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

Parameters:

oldPassword - the old password

user - the user

Returns:

the string

getUser

public IUser 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 the user names.

Returns:

the user names

getCurrentUser

public IUser getCurrentUser()

Returns the currently logged in User.

Returns:

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

setCurrentUser

public void setCurrentUser(IUser 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.

Parameters:

password - the password

accountName - the account name

Returns:

the string

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

Validate password strength.

Parameters:

accountName - the account name

Returns:

true, if successful

Throws:

AuthenticationException - the authentication exception

verifyPasswordStrength

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

Validate password strength.

Parameters:

newPassword - the new password

oldPassword - the old password

Returns:

true, if successful

Throws:

AuthenticationException - the authentication exception

exists

public boolean exists(java.lang.String accountName)

Verifies the account exists.

Parameters:

accountName - the account name

Returns:

true, if successful