org.apache.shiro.authc
Class UsernamePasswordToken

java.lang.Object
  org.apache.shiro.authc.UsernamePasswordToken

All Implemented Interfaces:

Serializable, AuthenticationToken, HostAuthenticationToken, RememberMeAuthenticationToken

public class UsernamePasswordToken
extends Object
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 occuring.

"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 Java Cryptography Extension Reference Guide.

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

UsernamePasswordToken()
JavaBeans compatible no-arg constructor.

UsernamePasswordToken(String 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.

UsernamePasswordToken(String 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.

UsernamePasswordToken(String username, char[] password, boolean rememberMe, String 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 ocurring.

UsernamePasswordToken(String username, char[] password, String 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

UsernamePasswordToken(String username, String 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

UsernamePasswordToken(String username, String 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.

UsernamePasswordToken(String username, String password, boolean rememberMe, String 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 ocurring.

UsernamePasswordToken(String username, String password, String 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

void	clear() Clears out (nulls) the username, password, rememberMe, and inetAddress.
Object	getCredentials() Returns the password char array.
String	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.
Object	getPrincipal() Simply returns getUsername().
String	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	setHost(String 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 (pricipal(s)) to be remembered across sessions.
void	setUsername(String username) Sets the username for submission during an authentication attempt.
String	toString() Returns the String representation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UsernamePasswordToken

public UsernamePasswordToken()

JavaBeans compatible no-arg constructor.

UsernamePasswordToken

public UsernamePasswordToken(String 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(String username,
                             String 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 convience 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(String username,
                             char[] password,
                             String 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 occuring

Since:

0.2

UsernamePasswordToken

public UsernamePasswordToken(String username,
                             String password,
                             String 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 convience 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 occuring

Since:

1.0

UsernamePasswordToken

public UsernamePasswordToken(String 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(String username,
                             String 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 convience 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(String username,
                             char[] password,
                             boolean rememberMe,
                             String 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 ocurring.

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 occuring

Since:

1.0

UsernamePasswordToken

public UsernamePasswordToken(String username,
                             String password,
                             boolean rememberMe,
                             String 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 ocurring.

This is a convience 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 occuring

Since:

1.0

Method Detail

getUsername

public String getUsername()

Returns the username submitted during an authentication attempt.

Returns:

the username submitted during an authentication attempt.

setUsername

public void setUsername(String 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 attemp.

getPrincipal

public Object getPrincipal()

Simply returns getUsername().

Specified by:

getPrincipal in interface AuthenticationToken

Returns:

the username.

See Also:

AuthenticationToken.getPrincipal()

getCredentials

public Object getCredentials()

Returns the password char array.

Specified by:

getCredentials in interface AuthenticationToken

Returns:

the password char array.

See Also:

AuthenticationToken.getCredentials()

getHost

public String 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(String 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 occuring

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 (pricipal(s)) to be remembered across sessions. Unless overridden, the default value is false, indicating not to be remembered across sessions.

Parameters:

rememberMe - value inidicating 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 String toString()

Returns the String representation. It does not include the password in the resulting string for security reasons to prevent accidentially printing out a password that might be widely viewable).

Overrides:

toString in class Object

Returns:

the String representation of the UsernamePasswordToken, omitting the password.