org.owasp.esapi
Interface User

All Superinterfaces:

java.security.Principal, java.io.Serializable

All Known Implementing Classes:

DefaultUser

public interface User
extends java.security.Principal, java.io.Serializable

The User interface represents an application user or user account. There is quite a lot of information that an application must store for each user in order to enforce security properly. There are also many rules that govern authentication and identity management.

A user account can be in one of several states. When first created, a User should be disabled, not expired, and unlocked. To start using the account, an administrator should enable the account. The account can be locked for a number of reasons, most commonly because they have failed login for too many times. Finally, the account can expire after the expiration date has been reached. The User must be enabled, not expired, and unlocked in order to pass authentication.

Since:

June 1, 2007

Author:

Jeff Williams at Aspect Security, Chris Schmidt (chrisisbeef .at. gmail.com) Digital Ritual Software

Field Summary

static User

ANONYMOUS The ANONYMOUS user is used to represent an unidentified user.

Method Summary

void	addRole(java.lang.String role) Adds a role to this user's account.
void	addRoles(java.util.Set<java.lang.String> newRoles) Adds a set of roles to this user's account.
void	addSession(javax.servlet.http.HttpSession s) Adds a session for this User.
void	changePassword(java.lang.String oldPassword, java.lang.String newPassword1, java.lang.String newPassword2) Sets the user's password, performing a verification of the user's old password, the equality of the two new passwords, and the strength of the new password.
void	disable() Disable this user's account.
void	enable() Enable this user's account.
long	getAccountId() Gets this user's account id number.
java.lang.String	getAccountName() Gets this user's account name.
java.lang.String	getCSRFToken() Gets the CSRF token for this user's current sessions.
java.util.HashMap	getEventMap() Returns the hashmap used to store security events for this user.
java.util.Date	getExpirationTime() Returns the date that this user's account will expire.
int	getFailedLoginCount() Returns the number of failed login attempts since the last successful login for an account.
java.util.Date	getLastFailedLoginTime() Returns the date of the last failed login time for a user.
java.lang.String	getLastHostAddress() Returns the last host address used by the user.
java.util.Date	getLastLoginTime() Returns the date of the last successful login time for a user.
java.util.Date	getLastPasswordChangeTime() Gets the date of user's last password change.
java.util.Locale	getLocale()
java.util.Set<java.lang.String>	getRoles() Gets the roles assigned to a particular account.
java.lang.String	getScreenName() Gets the screen name (alias) for the current user.
java.util.Set	getSessions() Returns the list of sessions associated with this User.
void	incrementFailedLoginCount() Increment failed login count.
boolean	isAnonymous() Checks if user is anonymous.
boolean	isEnabled() Checks if this user's account is currently enabled.
boolean	isExpired() Checks if this user's account is expired.
boolean	isInRole(java.lang.String role) Checks if this user's account is assigned a particular role.
boolean	isLocked() Checks if this user's account is locked.
boolean	isLoggedIn() Tests to see if the user is currently logged in.
boolean	isSessionAbsoluteTimeout() Tests to see if this user's session has exceeded the absolute time out based on ESAPI's configuration settings.
boolean	isSessionTimeout() Tests to see if the user's session has timed out from inactivity based on ESAPI's configuration settings.
void	lock() Lock this user's account.
void	loginWithPassword(java.lang.String password) Login with password.
void	logout() Logout this user.
void	removeRole(java.lang.String role) Removes a role from this user's account.
void	removeSession(javax.servlet.http.HttpSession s) Removes a session for this User.
java.lang.String	resetCSRFToken() Returns a token to be used as a prevention against CSRF attacks.
void	setAccountName(java.lang.String accountName) Sets this user's account name.
void	setExpirationTime(java.util.Date expirationTime) Sets the date and time when this user's account will expire.
void	setLastFailedLoginTime(java.util.Date lastFailedLoginTime) Set the time of the last failed login for this user.
void	setLastHostAddress(java.lang.String remoteHost) Set the last remote host address used by this user.
void	setLastLoginTime(java.util.Date lastLoginTime) Set the time of the last successful login for this user.
void	setLastPasswordChangeTime(java.util.Date lastPasswordChangeTime) Set the time of the last password change for this user.
void	setLocale(java.util.Locale locale)
void	setRoles(java.util.Set<java.lang.String> roles) Sets the roles for this account.
void	setScreenName(java.lang.String screenName) Sets the screen name (username alias) for this user.
void	unlock() Unlock this user's account.
boolean	verifyPassword(java.lang.String password) Verify that the supplied password matches the password for this user.

Methods inherited from interface java.security.Principal

equals, getName, hashCode, toString

Field Detail

ANONYMOUS

static final User ANONYMOUS

The ANONYMOUS user is used to represent an unidentified user. Since there is always a real user, the ANONYMOUS user is better than using null to represent this.

Method Detail

getLocale

java.util.Locale getLocale()

Returns:

the locale

setLocale

void setLocale(java.util.Locale locale)

Parameters:

locale - the locale to set

addRole

void addRole(java.lang.String role)
             throws AuthenticationException

Adds a role to this user's account.

Parameters:

role - the role to add

Throws:

AuthenticationException - the authentication exception

addRoles

void addRoles(java.util.Set<java.lang.String> newRoles)
              throws AuthenticationException

Adds a set of roles to this user's account.

Parameters:

newRoles - the new roles to add

Throws:

AuthenticationException - the authentication exception

changePassword

void changePassword(java.lang.String oldPassword,
                    java.lang.String newPassword1,
                    java.lang.String newPassword2)
                    throws AuthenticationException,
                           EncryptionException

Sets the user's password, performing a verification of the user's old password, the equality of the two new passwords, and the strength of the new password.

Parameters:

oldPassword - the old password

newPassword1 - the new password

newPassword2 - the new password - used to verify that the new password was typed correctly

Throws:

AuthenticationException - if newPassword1 does not match newPassword2, if oldPassword does not match the stored old password, or if the new password does not meet complexity requirements

EncryptionException

disable

void disable()

Disable this user's account.

enable

void enable()

Enable this user's account.

getAccountId

long getAccountId()

Gets this user's account id number.

Returns:

the account id

getAccountName

java.lang.String getAccountName()

Gets this user's account name.

Returns:

the account name

getCSRFToken

java.lang.String getCSRFToken()

Gets the CSRF token for this user's current sessions.

Returns:

the CSRF token

getExpirationTime

java.util.Date getExpirationTime()

Returns the date that this user's account will expire.

Returns:

Date representing the account expiration time.

getFailedLoginCount

int getFailedLoginCount()

Returns the number of failed login attempts since the last successful login for an account. This method is intended to be used as a part of the account lockout feature, to help protect against brute force attacks. However, the implementor should be aware that lockouts can be used to prevent access to an application by a legitimate user, and should consider the risk of denial of service.

Returns:

the number of failed login attempts since the last successful login

getLastHostAddress

java.lang.String getLastHostAddress()

Returns the last host address used by the user. This will be used in any log messages generated by the processing of this request.

Returns:

the last host address used by the user

getLastFailedLoginTime

java.util.Date getLastFailedLoginTime()
                                      throws AuthenticationException

Returns the date of the last failed login time for a user. This date should be used in a message to users after a successful login, to notify them of potential attack activity on their account.

Returns:

date of the last failed login

Throws:

AuthenticationException - the authentication exception

getLastLoginTime

java.util.Date getLastLoginTime()

Returns the date of the last successful login time for a user. This date should be used in a message to users after a successful login, to notify them of potential attack activity on their account.

Returns:

date of the last successful login

getLastPasswordChangeTime

java.util.Date getLastPasswordChangeTime()

Gets the date of user's last password change.

Returns:

the date of last password change

getRoles

java.util.Set<java.lang.String> getRoles()

Gets the roles assigned to a particular account.

Returns:

an immutable set of roles

getScreenName

java.lang.String getScreenName()

Gets the screen name (alias) for the current user.

Returns:

the screen name

addSession

void addSession(javax.servlet.http.HttpSession s)

Adds a session for this User.

Parameters:

s - The session to associate with this user.

removeSession

void removeSession(javax.servlet.http.HttpSession s)

Removes a session for this User.

Parameters:

s - The session to remove from being associated with this user.

getSessions

java.util.Set getSessions()

Returns the list of sessions associated with this User.

Returns:

incrementFailedLoginCount

void incrementFailedLoginCount()

Increment failed login count.

isAnonymous

boolean isAnonymous()

Checks if user is anonymous.

Returns:

true, if user is anonymous

isEnabled

boolean isEnabled()

Checks if this user's account is currently enabled.

Returns:

true, if account is enabled

isExpired

boolean isExpired()

Checks if this user's account is expired.

Returns:

true, if account is expired

isInRole

boolean isInRole(java.lang.String role)

Checks if this user's account is assigned a particular role.

Parameters:

role - the role for which to check

Returns:

true, if role has been assigned to user

isLocked

boolean isLocked()

Checks if this user's account is locked.

Returns:

true, if account is locked

isLoggedIn

boolean isLoggedIn()

Tests to see if the user is currently logged in.

Returns:

true, if the user is logged in

isSessionAbsoluteTimeout

boolean isSessionAbsoluteTimeout()

Tests to see if this user's session has exceeded the absolute time out based on ESAPI's configuration settings.

Returns:

true, if user's session has exceeded the absolute time out

isSessionTimeout

boolean isSessionTimeout()

Tests to see if the user's session has timed out from inactivity based on ESAPI's configuration settings. A session may timeout prior to ESAPI's configuration setting due to the servlet container setting for session-timeout in web.xml. The following is an example of a web.xml session-timeout set for one hour. 60

Returns:

true, if user's session has timed out from inactivity based on ESAPI configuration

lock

void lock()

Lock this user's account.

loginWithPassword

void loginWithPassword(java.lang.String password)
                       throws AuthenticationException

Login with password.

Parameters:

password - the password

Throws:

AuthenticationException - if login fails

logout

void logout()

Logout this user.

removeRole

void removeRole(java.lang.String role)
                throws AuthenticationException

Removes a role from this user's account.

Parameters:

role - the role to remove

Throws:

AuthenticationException - the authentication exception

resetCSRFToken

java.lang.String resetCSRFToken()
                                throws AuthenticationException

Returns a token to be used as a prevention against CSRF attacks. This token should be added to all links and forms. The application should verify that all requests contain the token, or they may have been generated by a CSRF attack. It is generally best to perform the check in a centralized location, either a filter or controller. See the verifyCSRFToken method.

Returns:

the new CSRF token

Throws:

AuthenticationException - the authentication exception

setAccountName

void setAccountName(java.lang.String accountName)

Sets this user's account name.

Parameters:

accountName - the new account name

setExpirationTime

void setExpirationTime(java.util.Date expirationTime)

Sets the date and time when this user's account will expire.

Parameters:

expirationTime - the new expiration time

setRoles

void setRoles(java.util.Set<java.lang.String> roles)
              throws AuthenticationException

Sets the roles for this account.

Parameters:

roles - the new roles

Throws:

AuthenticationException - the authentication exception

setScreenName

void setScreenName(java.lang.String screenName)

Sets the screen name (username alias) for this user.

Parameters:

screenName - the new screen name

unlock

void unlock()

Unlock this user's account.

verifyPassword

boolean verifyPassword(java.lang.String password)
                       throws EncryptionException

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:

password - the password that the user entered

Returns:

true, if the password passed in matches the account's password

Throws:

EncryptionException

setLastFailedLoginTime

void setLastFailedLoginTime(java.util.Date lastFailedLoginTime)

Set the time of the last failed login for this user.

Parameters:

lastFailedLoginTime - the date and time when the user just failed to login correctly.

setLastHostAddress

void setLastHostAddress(java.lang.String remoteHost)
                        throws AuthenticationHostException

Set the last remote host address used by this user.

Parameters:

remoteHost - The address of the user's current source host.

Throws:

AuthenticationHostException

setLastLoginTime

void setLastLoginTime(java.util.Date lastLoginTime)

Set the time of the last successful login for this user.

Parameters:

lastLoginTime - the date and time when the user just successfully logged in.

setLastPasswordChangeTime

void setLastPasswordChangeTime(java.util.Date lastPasswordChangeTime)

Set the time of the last password change for this user.

Parameters:

lastPasswordChangeTime - the date and time when the user just successfully changed his/her password.

getEventMap

java.util.HashMap getEventMap()

Returns the hashmap used to store security events for this user. Used by the IntrusionDetector.