Package 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
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description 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 a Set containing the 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.
-
-
-
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 passwordnewPassword1
- the new passwordnewPassword2
- 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 requirementsEncryptionException
-
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 a Set containing the sessions associated with this User.- Returns:
- The Set of sessions for this User.
-
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.
-
-