org.owasp.esapi
Class Authenticator

java.lang.Object
  org.owasp.esapi.Authenticator

All Implemented Interfaces:

IAuthenticator

public class Authenticator

extends java.lang.Object

implements IAuthenticator

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:

IAuthenticator

Constructor Summary

Authenticator()

Method Summary

void	clearCurrent() Clears all threadlocal variables from the thread.
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) Gets the user object with the matching account name or null if there is no match.
IUser	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.
IUser	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(IUser user) Sets the currently logged in User.
void	verifyAccountNameStrength(java.lang.String newAccountName) Validate password strength.
void	verifyPasswordStrength(java.lang.String newPassword, java.lang.String oldPassword) Validate password strength.
boolean	verifyRememberToken() Verifies the current User's remember cookie from the current request.

Methods inherited from class java.lang.Object

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

Constructor Detail

Authenticator

public Authenticator()

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 IAuthenticator

createUser

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

Description copied from interface: IAuthenticator

Creates the user.

Specified by:

createUser in interface IAuthenticator

Parameters:

accountName - the account name

password1 - the password

password2 - copy of the password

Returns:

the new User object

Throws:

AuthenticationException - the authentication exception

exists

public boolean exists(java.lang.String accountName)

Description copied from interface: IAuthenticator

Verifies the account exists.

Specified by:

exists in interface IAuthenticator

Parameters:

accountName - the account name

Returns:

true, if successful

generateStrongPassword

public java.lang.String generateStrongPassword()

Description copied from interface: IAuthenticator

Generate a strong password.

Specified by:

generateStrongPassword in interface IAuthenticator

Returns:

the string

generateStrongPassword

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

Description copied from interface: IAuthenticator

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

Specified by:

generateStrongPassword in interface IAuthenticator

Parameters:

oldPassword - the old password

user - the user

Returns:

the string

getCurrentUser

public IUser getCurrentUser()

Description copied from interface: IAuthenticator

Returns the currently logged in User.

Specified by:

getCurrentUser in interface IAuthenticator

Returns:

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

getUser

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

Parameters:

accountName - the account name

Returns:

the user, or null if not matched.

getUserFromSession

public IUser getUserFromSession()

Gets the user from session.

Returns:

the user from session

verifyRememberToken

public boolean verifyRememberToken()

Verifies the current User's remember cookie from the current request.

Returns:

getUserNames

public java.util.Set getUserNames()

Gets the user names.

Specified by:

getUserNames in interface IAuthenticator

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: IAuthenticator

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.

Specified by:

hashPassword in interface IAuthenticator

Parameters:

password - the password

accountName - the account name

Returns:

the string

Throws:

EncryptionException

removeUser

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

Description copied from interface: IAuthenticator

Removes the account.

Specified by:

removeUser in interface IAuthenticator

Parameters:

accountName - the account name

Throws:

AuthenticationException - the authentication exception

login

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

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 IAuthenticator

setCurrentUser

public void setCurrentUser(IUser user)

Description copied from interface: IAuthenticator

Sets the currently logged in User.

Specified by:

setCurrentUser in interface IAuthenticator

Parameters:

user - the current user

verifyAccountNameStrength

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

Description copied from interface: IAuthenticator

Validate password strength.

Specified by:

verifyAccountNameStrength in interface IAuthenticator

Parameters:

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

Description copied from interface: IAuthenticator

Validate password strength.

Specified by:

verifyPasswordStrength in interface IAuthenticator

Parameters:

newPassword - the new password

oldPassword - the old password

Returns:

true, if successful

Throws:

AuthenticationException - the authentication exception