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

      Fields 
      Modifier and Type Field Description
      static User ANONYMOUS
      The ANONYMOUS user is used to represent an unidentified user.
    • 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 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, implies, 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
      • 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.
      • logout

        void logout()
        Logout this user.
      • 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
      • 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.