org.owasp.esapi.reference
Class FileBasedAuthenticator

java.lang.Object
  org.owasp.esapi.reference.FileBasedAuthenticator

All Implemented Interfaces:

Authenticator

public class FileBasedAuthenticator

extends java.lang.Object

implements Authenticator

Reference implementation of the IAuthenticator interface. This reference implementation is backed by a simple text file that contains serialized information about users. Many organizations will want to create their own implementation of the methods provided in the IAuthenticator interface backed by their own user repository. This reference implementation captures information about users in a simple text file format that contains user information separated by the pipe "|" character. Here's an example of a single line from the users.txt file:

 
 account name | hashed password | roles | lockout | status | remember token | old password hashes | last
 hostname | last change | last login | last failed | expiration | failed
 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 mitch | 44k/NAzQUlrCq9musTGGkcMNmdzEGJ8w8qZTLzpxLuQ= | admin,user | unlocked | enabled | token |
 u10dW4vTo3ZkoM5xP+blayWCz7KdPKyKUojOn9GJobg= | 192.168.1.255 | 1187201000926 | 1187200991568 | 1187200605330 |
 2187200605330 | 1
 
 

Since:

June 1, 2007

Author:

Jeff Williams at Aspect Security

See Also:

Authenticator

Constructor Summary

FileBasedAuthenticator()

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 all threadlocal variables from the thread.
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) Gets the user object with the matching account name or null if there is no match.
User	getUserFromSession() Gets the user from session.
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.
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() Log out the current user.
static void	main(java.lang.String[] args) Fail safe main program to add or update an account in an emergency.
void	removeUser(java.lang.String accountName) Removes the account.
void	setCurrentUser(User user) Sets the currently logged in User.
void	verifyAccountNameStrength(java.lang.String newAccountName) 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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileBasedAuthenticator

public FileBasedAuthenticator()

Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Fail safe main program to add or update an account in an emergency.

Warning: this method does not perform the level of validation and checks generally required in ESAPI, and can therefore be used to create a username and password that do not comply with the username and password strength requirements.

Example: Use this to add the alice account with the admin role to the users file:

 
 java -Dorg.owasp.esapi.resources="/path/resources" -classpath esapi.jar org.owasp.esapi.Authenticator alice password admin
 
 

Parameters:

args - the args

Throws:

AuthenticationException - the authentication exception

java.lang.Exception

clearCurrent

public void clearCurrent()

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.

Specified by:

clearCurrent in interface Authenticator

createUser

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

Description copied from interface: Authenticator

Creates the user.

Specified by:

createUser in interface Authenticator

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()?

exists

public boolean exists(java.lang.String accountName)

Description copied from interface: Authenticator

Determine if the account already exists.

Specified by:

exists in interface Authenticator

Parameters:

accountName - the account name

Returns:

true, if the account exists

generateStrongPassword

public java.lang.String generateStrongPassword()

Description copied from interface: Authenticator

Generate a strong password.

Specified by:

generateStrongPassword in interface Authenticator

Returns:

the string

changePassword

public void changePassword(User user,
                           java.lang.String currentPassword,
                           java.lang.String newPassword,
                           java.lang.String newPassword2)
                    throws AuthenticationException

Description copied from interface: Authenticator

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.

Specified by:

changePassword in interface Authenticator

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

verifyPassword

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

Description copied from interface: Authenticator

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.

Specified by:

verifyPassword in interface Authenticator

Parameters:

user - the user

password - the password

Returns:

true if the password is correct for the specified user

generateStrongPassword

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

Description copied from interface: Authenticator

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

Specified by:

generateStrongPassword in interface Authenticator

Parameters:

oldPassword - the old password

user - the user

Returns:

the new password

getCurrentUser

public User getCurrentUser()

Description copied from interface: Authenticator

Returns the currently logged in User.

Specified by:

getCurrentUser in interface Authenticator

Returns:

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

getUser

public User getUser(java.lang.String accountName)

Gets the user object with the matching account name or null if there is no match.

Specified by:

getUser in interface Authenticator

Parameters:

accountName - the account name

Returns:

the user, or null if not matched.

getUserFromSession

public User getUserFromSession()

Gets the user from session.

Returns:

the user from session

getUserNames

public java.util.Set getUserNames()

Gets the user names.

Specified by:

getUserNames in interface Authenticator

Returns:

list of user account names

hashPassword

public java.lang.String hashPassword(java.lang.String password,
                                     java.lang.String accountName)
                              throws EncryptionException

Description copied from interface: Authenticator

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.

Specified by:

hashPassword in interface Authenticator

Parameters:

password - the password

accountName - the account name

Returns:

the hashed password

Throws:

EncryptionException

removeUser

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

Description copied from interface: Authenticator

Removes the account.

Specified by:

removeUser in interface Authenticator

Parameters:

accountName - the account name

Throws:

AuthenticationException - the authentication exception

login

public 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. This method also checks that the user's access is still enabled, unlocked, and unexpired before allowing login. For convenience this method also returns the current user.

Specified by:

login in interface Authenticator

Parameters:

request - the request

response - the response

Returns:

the user

Throws:

AuthenticationException - the authentication exception

logout

public void logout()

Log out the current user.

Specified by:

logout in interface Authenticator

setCurrentUser

public void setCurrentUser(User user)

Description copied from interface: Authenticator

Sets the currently logged in User.

Specified by:

setCurrentUser in interface Authenticator

Parameters:

user - the current user

verifyAccountNameStrength

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

Description copied from interface: Authenticator

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

Specified by:

verifyAccountNameStrength in interface Authenticator

Parameters:

newAccountName - 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

Description copied from interface: Authenticator

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.

Specified by:

verifyPasswordStrength in interface Authenticator

Parameters:

oldPassword - the old password

newPassword - the new password

Returns:

true, if successful

Throws:

AuthenticationException - the authentication exception