Package org.apache.shiro.authc

Class UsernamePasswordToken

  • All Implemented Interfaces:
    , AuthenticationToken, HostAuthenticationToken, RememberMeAuthenticationToken
    public class UsernamePasswordToken
extends 
implements HostAuthenticationToken, RememberMeAuthenticationToken

    A simple username/password authentication token to support the most widely-used authentication mechanism. This class also implements the RememberMeAuthenticationToken interface to support "Remember Me" services across user sessions as well as the HostAuthenticationToken interface to retain the host name or IP address location from where the authentication attempt is occurring.

    "Remember Me" authentications are disabled by default, but if the application developer wishes to allow it for a login attempt, all that is necessary is to call setRememberMe(true). If the underlying SecurityManager implementation also supports RememberMe services, the user's identity will be remembered across sessions.

    Note that this class stores a password as a char[] instead of a String (which may seem more logical). This is because Strings are immutable and their internal value cannot be overwritten - meaning even a nulled String instance might be accessible in memory at a later time (e.g. memory dump). This is not good for sensitive information such as passwords. For more information, see the .

    To avoid this possibility of later memory access, the application developer should always call clear() after using the token to perform a login attempt.

    Since:
    0.1
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      UsernamePasswordToken()
      JavaBeans compatible no-arg constructor.
       username, char[] password)
      Constructs a new UsernamePasswordToken encapsulating the username and password submitted during an authentication attempt, with a null host and a rememberMe default of false.
       username, char[] password, boolean rememberMe)
      Constructs a new UsernamePasswordToken encapsulating the username and password submitted, as well as if the user wishes their identity to be remembered across sessions.
       username, char[] password, boolean rememberMe,  host)
      Constructs a new UsernamePasswordToken encapsulating the username and password submitted, if the user wishes their identity to be remembered across sessions, and the inetAddress from where the attempt is occurring.
       username, char[] password,  host)
      Constructs a new UsernamePasswordToken encapsulating the username and password submitted, the inetAddress from where the attempt is occurring, and a default rememberMe value of false
       username,  password)
      Constructs a new UsernamePasswordToken encapsulating the username and password submitted during an authentication attempt, with a null host and a rememberMe default of false
       username,  password, boolean rememberMe)
      Constructs a new UsernamePasswordToken encapsulating the username and password submitted, as well as if the user wishes their identity to be remembered across sessions.
       username,  password, boolean rememberMe,  host)
      Constructs a new UsernamePasswordToken encapsulating the username and password submitted, if the user wishes their identity to be remembered across sessions, and the inetAddress from where the attempt is occurring.
       username,  password,  host)
      Constructs a new UsernamePasswordToken encapsulating the username and password submitted, the inetAddress from where the attempt is occurring, and a default rememberMe value of false

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clear()
      Clears out (nulls) the username, password, rememberMe, and inetAddress.
      getCredentials()
      Returns the password char array.
      getHost()
      Returns the host name or IP string from where the authentication attempt occurs.
      char[] getPassword()
      Returns the password submitted during an authentication attempt as a character array.
      getPrincipal()
      Simply returns getUsername().
      getUsername()
      Returns the username submitted during an authentication attempt.
      boolean isRememberMe()
      Returns true if the submitting user wishes their identity (principal(s)) to be remembered across sessions, false otherwise.
      void  host)
      Sets the host name or IP string from where the authentication attempt occurs.
      void setPassword​(char[] password)
      Sets the password for submission during an authentication attempt.
      void setRememberMe​(boolean rememberMe)
      Sets if the submitting user wishes their identity (principal(s)) to be remembered across sessions.
      void  username)
      Sets the username for submission during an authentication attempt.
      toString()
      Returns the String representation.

      • Methods inherited from class java.lang.

        , , , , , , , , ,

    • Constructor Detail

      • UsernamePasswordToken

        public UsernamePasswordToken()
        JavaBeans compatible no-arg constructor.

      • UsernamePasswordToken

        public UsernamePasswordToken​( username,
                             char[] password)
        Constructs a new UsernamePasswordToken encapsulating the username and password submitted during an authentication attempt, with a null host and a rememberMe default of false.
        Parameters:
        username - the username submitted for authentication
        password - the password character array submitted for authentication

      • UsernamePasswordToken

        public UsernamePasswordToken​( username,
                              password)
        Constructs a new UsernamePasswordToken encapsulating the username and password submitted during an authentication attempt, with a null host and a rememberMe default of false

        This is a convenience constructor and maintains the password internally via a character array, i.e. password.toCharArray();. Note that storing a password as a String in your code could have possible security implications as noted in the class JavaDoc.

        Parameters:
        username - the username submitted for authentication
        password - the password string submitted for authentication

      • UsernamePasswordToken

        public UsernamePasswordToken​( username,
                             char[] password,
                              host)
        Constructs a new UsernamePasswordToken encapsulating the username and password submitted, the inetAddress from where the attempt is occurring, and a default rememberMe value of false
        Parameters:
        username - the username submitted for authentication
        password - the password string submitted for authentication
        host - the host name or IP string from where the attempt is occurring
        Since:
        0.2

      • UsernamePasswordToken

        public UsernamePasswordToken​( username,
                              password,
                              host)
        Constructs a new UsernamePasswordToken encapsulating the username and password submitted, the inetAddress from where the attempt is occurring, and a default rememberMe value of false

        This is a convenience constructor and maintains the password internally via a character array, i.e. password.toCharArray();. Note that storing a password as a String in your code could have possible security implications as noted in the class JavaDoc.

        Parameters:
        username - the username submitted for authentication
        password - the password string submitted for authentication
        host - the host name or IP string from where the attempt is occurring
        Since:
        1.0

      • UsernamePasswordToken

        public UsernamePasswordToken​( username,
                             char[] password,
                             boolean rememberMe)
        Constructs a new UsernamePasswordToken encapsulating the username and password submitted, as well as if the user wishes their identity to be remembered across sessions.
        Parameters:
        username - the username submitted for authentication
        password - the password string submitted for authentication
        rememberMe - if the user wishes their identity to be remembered across sessions
        Since:
        0.9

      • UsernamePasswordToken

        public UsernamePasswordToken​( username,
                              password,
                             boolean rememberMe)
        Constructs a new UsernamePasswordToken encapsulating the username and password submitted, as well as if the user wishes their identity to be remembered across sessions.

        This is a convenience constructor and maintains the password internally via a character array, i.e. password.toCharArray();. Note that storing a password as a String in your code could have possible security implications as noted in the class JavaDoc.

        Parameters:
        username - the username submitted for authentication
        password - the password string submitted for authentication
        rememberMe - if the user wishes their identity to be remembered across sessions
        Since:
        0.9

      • UsernamePasswordToken

        public UsernamePasswordToken​( username,
                             char[] password,
                             boolean rememberMe,
                              host)
        Constructs a new UsernamePasswordToken encapsulating the username and password submitted, if the user wishes their identity to be remembered across sessions, and the inetAddress from where the attempt is occurring.
        Parameters:
        username - the username submitted for authentication
        password - the password character array submitted for authentication
        rememberMe - if the user wishes their identity to be remembered across sessions
        host - the host name or IP string from where the attempt is occurring
        Since:
        1.0

      • UsernamePasswordToken

        public UsernamePasswordToken​( username,
                              password,
                             boolean rememberMe,
                              host)
        Constructs a new UsernamePasswordToken encapsulating the username and password submitted, if the user wishes their identity to be remembered across sessions, and the inetAddress from where the attempt is occurring.

        This is a convenience constructor and maintains the password internally via a character array, i.e. password.toCharArray();. Note that storing a password as a String in your code could have possible security implications as noted in the class JavaDoc.

        Parameters:
        username - the username submitted for authentication
        password - the password string submitted for authentication
        rememberMe - if the user wishes their identity to be remembered across sessions
        host - the host name or IP string from where the attempt is occurring
        Since:
        1.0

    • Method Detail

      • getUsername

        public  getUsername()
        Returns the username submitted during an authentication attempt.
        Returns:
        the username submitted during an authentication attempt.

      • setUsername

        public void setUsername​( username)
        Sets the username for submission during an authentication attempt.
        Parameters:
        username - the username to be used for submission during an authentication attempt.

      • getPassword

        public char[] getPassword()
        Returns the password submitted during an authentication attempt as a character array.
        Returns:
        the password submitted during an authentication attempt as a character array.

      • setPassword

        public void setPassword​(char[] password)
        Sets the password for submission during an authentication attempt.
        Parameters:
        password - the password to be used for submission during an authentication attempt.

      • getHost

        public  getHost()
        Returns the host name or IP string from where the authentication attempt occurs. May be null if the host name/IP is unknown or explicitly omitted. It is up to the Authenticator implementation processing this token if an authentication attempt without a host is valid or not.

        (Shiro's default Authenticator allows null hosts to support localhost and proxy server environments).

        Specified by:
        getHost in interface HostAuthenticationToken
        Returns:
        the host from where the authentication attempt occurs, or null if it is unknown or explicitly omitted.
        Since:
        1.0

      • setHost

        public void setHost​( host)
        Sets the host name or IP string from where the authentication attempt occurs. It is up to the Authenticator implementation processing this token if an authentication attempt without a host is valid or not.

        (Shiro's default Authenticator allows null hosts to allow localhost and proxy server environments).

        Parameters:
        host - the host name or IP string from where the attempt is occurring
        Since:
        1.0

      • isRememberMe

        public boolean isRememberMe()
        Returns true if the submitting user wishes their identity (principal(s)) to be remembered across sessions, false otherwise. Unless overridden, this value is false by default.
        Specified by:
        isRememberMe in interface RememberMeAuthenticationToken
        Returns:
        true if the submitting user wishes their identity (principal(s)) to be remembered across sessions, false otherwise (false by default).
        Since:
        0.9

      • setRememberMe

        public void setRememberMe​(boolean rememberMe)
        Sets if the submitting user wishes their identity (principal(s)) to be remembered across sessions. Unless overridden, the default value is false, indicating not to be remembered across sessions.
        Parameters:
        rememberMe - value indicating if the user wishes their identity (principal(s)) to be remembered across sessions.
        Since:
        0.9

      • clear

        public void clear()
        Clears out (nulls) the username, password, rememberMe, and inetAddress. The password bytes are explicitly set to 0x00 before nulling to eliminate the possibility of memory access at a later time.

      • toString

        public  toString()
        Returns the String representation. It does not include the password in the resulting string for security reasons to prevent accidentally printing out a password that might be widely viewable).
        Overrides:
         in class 
        Returns:
        the String representation of the UsernamePasswordToken, omitting the password.