com.pingidentity.opentoken
Class Agent

java.lang.Object
  extended by com.pingidentity.opentoken.Agent

public class Agent
extends Object

Provides the methods necessary for generating and consuming a valid OpenToken cookie or query parameter.


Field Summary
static String OPENTOKEN_SYSTEM_DEBUG
          Debug flag for bypassing encryption for test purposes
static String TOKEN_NOT_BEFORE
          Key into token values collection for not-before value
static String TOKEN_NOT_ON_OR_AFTER
          Key into token values collection for not-on-or-after value
static String TOKEN_RENEW_UNTIL
          Key into token values collection for renew-until value
static String TOKEN_SUBJECT
          Key into token values collection for subject value
 
Constructor Summary
Agent()
          Constructs an Agent with default values.
Agent(AgentConfiguration configuration)
          Constructs an Agent using configuration from the provided AgentConfiguration.
Agent(boolean loadDefaultConfigurationFile)
          Constructs an Agent using configuration file on CLASSPATH.
Agent(InputStream configStream)
          Constructs an Agent using the configuration from the provided InputStream.
Agent(String file)
          Constructs an Agent using a configuration file on CLASSPATH.
 
Method Summary
static Map convertFromMultiMap(org.apache.commons.collections.MultiMap attributes)
           
static org.apache.commons.collections.MultiMap convertToMultiMap(Map attributes)
           
 void deleteToken(javax.servlet.http.HttpServletResponse response)
          Deletes the token from the provided response; applicable only when AgentConfiguration.isUseCookie() is true.
 AgentConfiguration getAgentConfiguration()
          Returns a copy of Agent configuration.
 String getLastError()
          This function should be used to generate log messages when the Agent encounters an error.
 void loadConfiguration(InputStream is)
          Deprecated. as of version 1.3
 Map readToken(javax.servlet.http.HttpServletRequest request)
          Reads key/value pairs stored in a token on the provided request.
 Map readToken(String token)
          Reads key/value pairs stored in a token string.
 org.apache.commons.collections.MultiMap readTokenToMultiMap(javax.servlet.http.HttpServletRequest request)
          Reads key/value(s) pairs stored in a token on the provided request.
 org.apache.commons.collections.MultiMap readTokenToMultiMap(String token)
          Reads key/value(s) pairs stored in a token string.
 String writeToken(Map ids)
          Writes map of key/value pairs to a new token, returns token as a string.
 void writeToken(Map ids, javax.servlet.http.HttpServletResponse response, String targetUrl)
          Writes map of key/value pairs to a new token, then redirects to targetUrl.
 void writeToken(Map ids, javax.servlet.http.HttpServletResponse response, UrlHelper targetUrl)
          Writes map of key/value pairs to a new token, then redirects to targetUrl.
 void writeToken(Map ids, javax.servlet.http.HttpServletResponse response, UrlHelper targetUrl, boolean doRedirect)
          Writes map of key/value pairs to a new token, then optionally redirects to targetUrl.
 String writeToken(org.apache.commons.collections.MultiMap ids)
          Writes map of key/value(s) pairs to a new token, returns token as a string.
 void writeToken(org.apache.commons.collections.MultiMap ids, javax.servlet.http.HttpServletResponse response, String targetUrl)
          Writes map key/value(s) pairs to a new token, then redirects to targetUrl.
 void writeToken(org.apache.commons.collections.MultiMap ids, javax.servlet.http.HttpServletResponse response, UrlHelper targetUrl)
          Writes map of key/value(s) pairs to a new token, then redirects to targetUrl.
 void writeToken(org.apache.commons.collections.MultiMap ids, javax.servlet.http.HttpServletResponse response, UrlHelper targetUrl, boolean doRedirect)
          Writes map of key/value(s) pairs to a new token, then optionally redirects to targetUrl.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TOKEN_SUBJECT

public static final String TOKEN_SUBJECT
Key into token values collection for subject value

See Also:
Constant Field Values

TOKEN_NOT_BEFORE

public static final String TOKEN_NOT_BEFORE
Key into token values collection for not-before value

See Also:
Constant Field Values

TOKEN_NOT_ON_OR_AFTER

public static final String TOKEN_NOT_ON_OR_AFTER
Key into token values collection for not-on-or-after value

See Also:
Constant Field Values

TOKEN_RENEW_UNTIL

public static final String TOKEN_RENEW_UNTIL
Key into token values collection for renew-until value

See Also:
Constant Field Values

OPENTOKEN_SYSTEM_DEBUG

public static final String OPENTOKEN_SYSTEM_DEBUG
Debug flag for bypassing encryption for test purposes

See Also:
Constant Field Values
Constructor Detail

Agent

public Agent()
Constructs an Agent with default values. Equivalent to Agent(false).


Agent

public Agent(boolean loadDefaultConfigurationFile)
Constructs an Agent using configuration file on CLASSPATH. Looks for file with name AgentConfiguration.AGENT_CONFIG_FILE_DEFALUT. If the file is not found, an Agent is constructed using default values.

Parameters:
loadDefaultConfigurationFile - if true, loads the configuration file with name AgentConfiguration.AGENT_CONFIG_FILE_DEFALUT located on the CLASSPATH if available; if false, an Agent is constructed using default values

Agent

public Agent(InputStream configStream)
      throws IOException
Constructs an Agent using the configuration from the provided InputStream.

Parameters:
configStream - an InputStream containing agent configuration
Throws:
IOException - when the configuration is invalid or the configStream generates an error

Agent

public Agent(AgentConfiguration configuration)
Constructs an Agent using configuration from the provided AgentConfiguration. This constructor is ideal for use with an IoC container, like Spring.

Example Spring configuration:
 <bean id='agent' class='com.pingidentity.opentoken.Agent'>
        <constructor-arg 
                type='com.pingidentity.opentoken.AgentConfiguration'>
                <bean class='com.pingidentity.opentoken.AgentConfiguration'>
                        <property name='cookieDomain' value='.example.com' />
                        <property name='cookiePath' value='/' />
                        <property name='notBeforeTolerance' value='120' />
                        <property name='password' value='welcome1'/>
                        <property name='cipherSuite' value="3"/>
                        <property name='renewUntilLifetime' value='43200' />
                        <property name='tokenLifetime' value='900' />
                        <property name='tokenName' value='opentoken' />
                        <property name='useCookie' value='true' />
                        <property name='sessionCookie' value='true' />
                        <property name='secureCookie' value='true' />
                </bean>
        </constructor-arg>
 </bean>
 

Parameters:
configuration - an AgentConfiguration containing agent configuration: copy of AgentConfiguration is made to prevent mutability
See Also:
org.apache.commons.beanutils.BeanUtils#cloneBean(java.lang.Object)

Agent

public Agent(String file)
      throws IOException
Constructs an Agent using a configuration file on CLASSPATH. If the file is not found on CLASSPATH, constructor attempts to use provided filename as a fully qualified path to a file.

Parameters:
file - filename on CLASSPATH or fully qualified path to the file on disk
Throws:
IOException
Method Detail

getLastError

public String getLastError()
This function should be used to generate log messages when the Agent encounters an error.

Returns:
a message string describing the last error encountered by the Agent

getAgentConfiguration

public AgentConfiguration getAgentConfiguration()
Returns a copy of Agent configuration.

Returns:

readToken

public Map readToken(String token)
              throws TokenException
Reads key/value pairs stored in a token string. If the return value is null (thus no token was present), getLastError() will provide an error message describing the problem.

Parameters:
token - as String
Returns:
Map of key/value pairs if successful
Throws:
TokenException - when the token is present but invalid, or decoding errors are encountered

readTokenToMultiMap

public org.apache.commons.collections.MultiMap readTokenToMultiMap(String token)
                                                            throws TokenException
Reads key/value(s) pairs stored in a token string. If the return value is null (thus no token was present), getLastError() will provide an error message describing the problem.

Parameters:
token - as String
Returns:
MultiMap of key/value(s) pairs if successful
Throws:
TokenException - when the token is present but invalid, or decoding errors are encountered

readToken

public Map readToken(javax.servlet.http.HttpServletRequest request)
              throws TokenException
Reads key/value pairs stored in a token on the provided request. If the return value is null (thus no token was present), getLastError() will provide an error message describing the problem.

Parameters:
request - HttpServletRequest containing the token in query parameter or cookie with name AgentConfiguration.getTokenName()
Returns:
Map of key/value pairs if successful
Throws:
TokenException - when the token is present but invalid, or decoding errors are encountered

readTokenToMultiMap

public org.apache.commons.collections.MultiMap readTokenToMultiMap(javax.servlet.http.HttpServletRequest request)
                                                            throws TokenException
Reads key/value(s) pairs stored in a token on the provided request. If the return value is null (thus no token was present), getLastError() will provide an error message describing the problem.

Parameters:
request - HttpServletRequest containing token in query parameter or cookie with name AgentConfiguration.getTokenName()
Returns:
MultiMap of key/value pairs if successful
Throws:
TokenException - when the token is present but invalid, or decoding errors are encountered
See Also:
org.apache.commons.collections.MultiMap

writeToken

public void writeToken(Map ids,
                       javax.servlet.http.HttpServletResponse response,
                       String targetUrl)
                throws MalformedURLException,
                       IOException,
                       TokenException
Writes map of key/value pairs to a new token, then redirects to targetUrl.

Parameters:
ids - map of key/value pairs
response - HttpServletResponse to write the token to
targetUrl - the URL to redirect to, once a token is written
Throws:
MalformedURLException - if the targetUrl is not a valid URL
IOException - if errors are encountered when writing the response
TokenException - if errors are encountered when encoding the token

writeToken

public void writeToken(org.apache.commons.collections.MultiMap ids,
                       javax.servlet.http.HttpServletResponse response,
                       String targetUrl)
                throws MalformedURLException,
                       IOException,
                       TokenException
Writes map key/value(s) pairs to a new token, then redirects to targetUrl.

Parameters:
ids - MultiMap of key/value(s) pairs
response - HttpServletResponse to write the token to
targetUrl - the URL to redirect to, once a token is written
Throws:
MalformedURLException - if the targetUrl is not a valid URL
IOException - if errors are encountered when writing the response
TokenException - if errors are encountered when encoding the token

writeToken

public void writeToken(Map ids,
                       javax.servlet.http.HttpServletResponse response,
                       UrlHelper targetUrl)
                throws IOException,
                       TokenException
Writes map of key/value pairs to a new token, then redirects to targetUrl.

Parameters:
ids - map of key/value pairs
response - HttpServletResponse to write the token to
targetUrl - the URL to redirect to, once a token is written
Throws:
IOException
TokenException

writeToken

public void writeToken(org.apache.commons.collections.MultiMap ids,
                       javax.servlet.http.HttpServletResponse response,
                       UrlHelper targetUrl)
                throws IOException,
                       TokenException
Writes map of key/value(s) pairs to a new token, then redirects to targetUrl.

Parameters:
ids - MultiMap of key/value(s) pairs
response - HttpServletResponse to write the token to
targetUrl - the URL to redirect to, once a token is written
Throws:
IOException
TokenException

writeToken

public void writeToken(Map ids,
                       javax.servlet.http.HttpServletResponse response,
                       UrlHelper targetUrl,
                       boolean doRedirect)
                throws IOException,
                       TokenException
Writes map of key/value pairs to a new token, then optionally redirects to targetUrl.

Parameters:
ids - map of key/value pairs
response - HttpServletResponse to write the token to
targetUrl - the URL to redirect to, once a token is written
doRedirect - flag indicating if the response should be automatically redirected to targetUrl
Throws:
IOException
TokenException

writeToken

public void writeToken(org.apache.commons.collections.MultiMap ids,
                       javax.servlet.http.HttpServletResponse response,
                       UrlHelper targetUrl,
                       boolean doRedirect)
                throws IOException,
                       TokenException
Writes map of key/value(s) pairs to a new token, then optionally redirects to targetUrl.

Parameters:
ids - map of key/value(s) pairs
response - HttpServletResponse to write the token to
targetUrl - the URL to redirect to, once a token is written
doRedirect - flag indicating if the response should be automatically redirected to targetUrl
Throws:
IOException
TokenException

writeToken

public String writeToken(Map ids)
                  throws TokenException
Writes map of key/value pairs to a new token, returns token as a string.

Parameters:
ids - map of key/value pairs
Returns:
an OpenToken as a String
Throws:
TokenException

writeToken

public String writeToken(org.apache.commons.collections.MultiMap ids)
                  throws TokenException
Writes map of key/value(s) pairs to a new token, returns token as a string.

Parameters:
ids - map of key/value(s) pairs
Returns:
an OpenToken in string form
Throws:
TokenException

loadConfiguration

public void loadConfiguration(InputStream is)
                       throws IOException
Deprecated. as of version 1.3

Reads agent configuration from an InputStream that was previously generated by storeConfiguration.

Parameters:
is - source of configuration data
Throws:
IOException

deleteToken

public void deleteToken(javax.servlet.http.HttpServletResponse response)
Deletes the token from the provided response; applicable only when AgentConfiguration.isUseCookie() is true.

Parameters:
response - the HttpServletResponse from which to delete the token

convertFromMultiMap

public static Map convertFromMultiMap(org.apache.commons.collections.MultiMap attributes)

convertToMultiMap

public static org.apache.commons.collections.MultiMap convertToMultiMap(Map attributes)


Copyright © 2012. All Rights Reserved.