org.opentox.toxotis.util.aa
Class AuthenticationToken

java.lang.Object
  extended by org.opentox.toxotis.util.aa.AuthenticationToken

public class AuthenticationToken
extends Object

OpenTox specific implementation regarding the token provided by the OpenSSO server. Client authenticates against OpenSSO server and obtains a token (a successful authentication identifier). The user data is drawn from the LDAP backend that also the Plone website uses (http://opentox.org). This token is used to permit or deny a client a specific action. The token encodes conjunction of user and point of time and has a certain lifetime. If a token is authorized for the action according to current server policy, the webservice performs the action.

Author:
Pantelis Sopasakis, Charalampos Chomenides
See Also:
Documentation (Draft), Authenticationa and Authorization API (OpenTox), Single Sign-on (SSO) in WikiPedia

Nested Class Summary
static class AuthenticationToken.TokenStatus
          Status of the token.
 
Constructor Summary
AuthenticationToken()
          Initialize a new Authentication Token.
AuthenticationToken(AuthenticationToken other)
          Construct an authentication token as a clone of an existing one.
AuthenticationToken(File file)
          Cosntruct an authentication token using a password file.
AuthenticationToken(String token)
          

Create a new token providing its String representation.

AuthenticationToken(String username, String password)
          

Create a new Authentication token providing your credentials.

 
Method Summary
 boolean authorize(String httpMethod, String target)
          Ask the SSO server whether the user with the given token is allowed to perform an HTTP operation on a target URI.
 boolean authorize(String httpMethod, VRI target)
          Ask the SSO server whether the user with the given token is allowed to perform an HTTP operation on a target URI.
 boolean equals(Object obj)
          Two Authentication tokens are equal to each other if and only if, none of them is null and they have the same string representation when non encoded.
 String getEncoding()
          Retrieve the encoding used to encode tokens.
 AuthenticationToken.TokenStatus getStatus()
          Get the status of the token.
 Date getTokenCreationDate()
           
 long getTokenCreationTimestamp()
          Retrieve the timestamp of the token creation.
 String getTokenUrlEncoded()
          Returns the token as a URL encoded String.
 User getUser()
          Information about the user that holds the token (for which the token was created).
 int hashCode()
           
 void invalidate()
          Sends an invalidation request to the remote server.
 void setEncoding(String encoding)
          Specify the standard encoding that should be used for the encoding of the token.
 String stringValue()
          Returns the token as a String (not URL encoded).
 String toString()
           
 boolean validate()
          Ask the remote SSO server whether this token is valid.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AuthenticationToken

public AuthenticationToken()
Initialize a new Authentication Token. The constructor also initializes the SSL connection with the openSSO server.

See Also:
Default SSO Server

AuthenticationToken

public AuthenticationToken(String token)

Create a new token providing its String representation. The timestamp of the constructor invocation is set as the creation timestamp of the token, but it has to the validated against the openSSO server using the method validate() to make sure that the token will be acceptable by OpenTox services. End users are adviced to prefer the constructor AuthenticationToken(java.lang.String, java.lang.String), providing their username and password.

Parameters:
token - The token as a String.

AuthenticationToken

public AuthenticationToken(String username,
                           String password)
                    throws ServiceInvocationException

Create a new Authentication token providing your credentials. These credentials are posted to the SSO AUTH server which (if they are valid) returns a token. This is used to construct a new Authentication Token object. The timestamp of the method invokation is set as the timestamp for the object construction. All data transactions take place over secure layers (SSL) and using encryption (TLS).

Parameters:
username - The username of an OpenTox user
password - The password of an OpenTox user
Throws:
ToxOtisException - In case the credentials are not valid, some exceptional event occurs during the data transaction or in case the SSO service returns an error code other than expected (e.g. encounters some internal error and returns a status code 500).
ServiceInvocationException

AuthenticationToken

public AuthenticationToken(AuthenticationToken other)
Construct an authentication token as a clone of an existing one.

Parameters:
other - An authentication token to be cloned.

AuthenticationToken

public AuthenticationToken(File file)
                    throws IOException,
                           ToxOtisException,
                           ServiceInvocationException
Cosntruct an authentication token using a password file. Password files are generated by the PasswordFileManager. Make sure that you have configured properly the password manager specifying the path of the master key file using the method setMasterPasswordFile.

Parameters:
file - Encrypted file containing your credentials.
Throws:
IOException - In case the the file is not found or cannot be read.
ToxOtisException - In case the credentials are not valid, some exceptional event occurs during the data transaction or in case the SSO service returns an error code other than expected (e.g. encounters some internal error and returns a status code 500).
ServiceInvocationException
Method Detail

getEncoding

public String getEncoding()
Retrieve the encoding used to encode tokens. The default value used in this implementation is 'UTF-8'.

Returns:
URL encoding standard.

setEncoding

public void setEncoding(String encoding)
Specify the standard encoding that should be used for the encoding of the token. This will affect the method getTokenUrlEncoded(). By default this is set to UTF-8.

Parameters:
encoding - Standard Encoding.

getStatus

public AuthenticationToken.TokenStatus getStatus()
Get the status of the token. Token status is characterized by the enumeration AuthenticationToken.TokenStatus.

Returns:
Status of the token as an element of AuthenticationToken.TokenStatus. Will return the value DEAD if the token was never successfully initialized, INACTIVE if the token was invalidated (logged out) of if it has expired, otherwise ACTIVE.

stringValue

public String stringValue()
Returns the token as a String (not URL encoded). Tokens are retrived by the remote openSSO server either using the constructor AuthenticationToken(String, String) or the PasswordFileManager (read documentation therein).

Returns:
Token as string; not encoded

getTokenUrlEncoded

public String getTokenUrlEncoded()
Returns the token as a URL encoded String.

Returns:
Token encoded using the UTF-8 encoding.

getTokenCreationTimestamp

public long getTokenCreationTimestamp()
Retrieve the timestamp of the token creation. If the difference between the current timestamp retrieved by System.currentTimeMillis() and the timestamp of the token creation exceeds TOKEN_LOCAL_LIFESPAN then the token is considered to be Inactive.

Returns:
The timestamp of the token creation
See Also:
getStatus()

getTokenCreationDate

public Date getTokenCreationDate()

validate

public boolean validate()
                 throws ServiceInvocationException
Ask the remote SSO server whether this token is valid. This method performs a (secure) connection to the validation service on the SSO server and POSTs the token. The RESTful API concerning A&A can be found online at http://opentox.org/dev/apis/api-1.1/AA.

Returns:
true if a positive response was returned from the remote server and false otherwise.
Throws:
ToxOtisException - In case an error status is received from the remote service or there is some communication problem.
ServiceInvocationException

invalidate

public void invalidate()
                throws ServiceInvocationException
Sends an invalidation request to the remote server. Once the token is invalidated it can no longer be used in any authentication/authorization sessions.

Throws:
ToxOtisException - In case an error status is received from the remote service or there is some communication problem.
ServiceInvocationException

getUser

public User getUser()
             throws ServiceInvocationException,
                    ToxOtisException
Information about the user that holds the token (for which the token was created).

Returns:
User information as an instance of User.
Throws:
ServiceInvocationException - In case the remote identity (SSO) service is not reachable/accessible at the moment or returns a 401/403 error HTTP code implying that the token is not valid.
ToxOtisException - If the mail is invalid

equals

public boolean equals(Object obj)
Two Authentication tokens are equal to each other if and only if, none of them is null and they have the same string representation when non encoded.

Overrides:
equals in class Object
Parameters:
obj - Some other object for which equality to the current authentication token is under examination.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
hashCode()

authorize

public boolean authorize(String httpMethod,
                         VRI target)
                  throws ServiceInvocationException
Ask the SSO server whether the user with the given token is allowed to perform an HTTP operation on a target URI. If the SSO server allows the action, then it replies with a status code 200 and the message boolean=true, otherwise it returns a response with the status code 401 (Unauthorized) and the plain text message boolean=false.

Parameters:
httpMethod - The HTTP for which permission is asked.
target - The action URI on which the HTTP method will be applied once permission is granted to the client.
Returns:
true if the user is allowed to perform the operation and false otherwise.
Throws:
ToxOtisException - If a connection problem occurs with the remote or the communication is corrupted.
InactiveTokenException - If the token the user uses is not active (because it has been invalidated, expired, or not initialized yet).
ServiceInvocationException

authorize

public boolean authorize(String httpMethod,
                         String target)
                  throws ServiceInvocationException
Ask the SSO server whether the user with the given token is allowed to perform an HTTP operation on a target URI. If the SSO server allows the action, then it replies with a status code 200 and the message boolean=true, otherwise it returns a response with the status code 401 (Unauthorized) and the plain text message boolean=false.

Parameters:
httpMethod - The HTTP for which permission is asked.
target - The action URI on which the HTTP method will be applied once permission is granted to the client. The target URI in this method is provided as a simple String.
Returns:
true if the user is allowed to perform the operation and false otherwise.
Throws:
ToxOtisException - If a connection problem occurs with the remote or the communication is corrupted or the provided target is not a valid URI.
ServiceInvocationException

hashCode

public int hashCode()
Overrides:
hashCode in class Object

toString

public String toString()
Overrides:
toString in class Object


Copyright © 2011-2012 OpenTox. All Rights Reserved.