CA Access Gateway APIs

This content describes the smsps APIs.
casso127
This content describes the 
CA Access Gateway
APIs.
3
Session Scheme API
The 
CA Access Gateway
 supports a Java API that allows you to develop custom session schemes. These schemes can be assigned to user agent types for each virtual host configured on the 
CA Access Gateway
.
Overview of Session Scheme API Processing
The 
CA Access Gateway
 processes a number of methods to establish, maintain, and end a typical user session. One of the steps during session processing is to determine whether a scheme is rewritable. Rewritable schemes provide the ability to modify the URL. The simple URL rewriting session scheme is an example of a rewritable scheme, since part of the processing of a request includes rewriting the requested URL to include a token.
To implement a rewritable session scheme, you must implement the rewritable interface, which is described in Configure Rewritable Session Schemes.
The following illustration shows the process flow for the session scheme API methods.
Session Scheme API Processing Flow
Session Scheme API Processing Flow
The methods identified in the illustration are:
  1. isValidRequest
     -- This method must be implemented in a custom session scheme to determine and verify the conditions that make up a valid request.
  2. getKeyFromRequest
     -- This method must be implemented to extract a key from a valid request. If no key is present, the createKeyFromRequest method is called.
  3. createKeyFromRequest
     -- This method must be implemented to trigger the creation of a key for a new session.
  4. onSessionCreate
     -- On the event of session creation, if the session scheme in use is not rewritable, this method is called. This method may be implemented with any code that should be triggered at the inception of a new session.
  5. onSessionCreateRedirect
     -- On the event of session creation, if the scheme is rewritable, this method is called. This method may be implemented with any code that should be called at the inception of a new session for a rewritable session scheme.
  6. onSessionUpdate
     -- A session is updated for each new request made during the session. This method is called during each session update. It may be implemented by adding any code that should be triggered during a session update.
  7. onSessionLogout
     -- This method is called when a session is terminated. It may be implemented with any code that should be executed when a user session is terminated.
Session Scheme API Class Files
The 
CA Access Gateway
 session scheme API makes use of the session scheme abstract class contained in 
sps_home
/Tomcat/server/lib/proxycore.jar.
Constructor for Session Scheme API
The constructor for a custom session scheme must consist of the following:
public IPAddrSessionScheme(String name, boolean
                acceptFlag, Hashtable props) {  
        // Always call the parent constructor for proper    
        // initialization of the scheme 
 
        super(name,acceptFlag,props);   
The settings are as follows:
  • name
    String that is populated by the name in the server.conf file associated with your custom session scheme class.
  • acceptFlag
    Boolean value that determines whether or not the custom session scheme accepts  SMSESSION cookies.
  • props
    List of name/value pairs for any other properties required by the session scheme as specified in the server.conf file.
Session Scheme API Methods
The session scheme API class consists of the following methods:
Return Value
Method
Notes
Boolean
acceptsCookies()
Retrieves the value of the acceptFlag from the accepts_smsession_cookies parameter of the session scheme in the server.conf file and returns a value indicating whether this scheme supports SMSESSION cookies.
abstract java.lang.String
createKeyFromRequest(HttpServletRequest req)
Executes code to retrieve values needed to create a new session key from the request.
abstract java.lang.String
getKeyFromRequest(HttpServletRequest req)
Retrieves the session key from a request.
java.lang.String
getName()
Retrieves the name of the custom session scheme as defined in the server.conf file.
abstract Boolean
isValidRequest(HttpServletRequest req)
Evaluates if the request for this session scheme is valid.
abstract int
onSessionCreate(java.lang.String id, HttpServletRequest req,
HttpServletResponse resp)
Hook that is available on the event of session creation.
java.lang.String
onSessionCreateRedirect(java.lang.String id, java.lang.String url, HttpServletRequest req, HttpServletResponse resp)
Hook that is available on the event of session creation for rewritable schemes. For example, SimpleURLSessionScheme. Implement the Rewritable interface for creating rewritable session schemes.
abstract void
onSessionLogOut(HttpServletRequest req,
HttpServletResponse resp)
Hook that is available at the event of a session termination (logout).
abstract void
onSessionUpdate(HttpServletRequest req, HttpServletResponse resp)
Hook that is available on the event of session updates. This method is only for internal use.
List<String>
getAllowedCookiesFromRequest(HttpServletRequest req)
Method for sending back the list of allowed cookies for the session scheme of a request.
static Boolean
usingDefaultSessionScheme(HttpServlet
Request req)
Helper method for recognizing that a request is using the default session scheme.
Implement a Custom Session Scheme
Use the following procedure to implement a custom session scheme.
Follow these steps:
  1. Review the sample code for the IP address session scheme in IP Address Session Scheme.
  2. Write source code for your session scheme.
  3. If you are creating a rewritable session scheme, implement the rewritable interface.
  4. Ensure that your system CLASSPATH includes the following content:
    • proxycore.jar which contains the session scheme API
    • JDK version 1.6.0_30 or higher jar files
    • sps_home
      /Tomcat/lib jar files
  5. Compile the session scheme.
  6. Do 
    one
     of the following steps:
    • Create a .jar file that contains your custom session schemes then copy the .jar file to the directory 
      sps_home/
      Tomcat/lib.
    • Add the class files for your custom session scheme in a jar in the 
      sps_home/
      Tomcat/lib directory then configure scheme in the 
      CA Access Gateway
       server.conf file.
  7. Restart the 
    CA Access Gateway
    .
Configure Custom Session Scheme in the server.conf File
When you compile the code for a custom session scheme you must configure the session scheme in the 
CA Access Gateway
 server.conf file. To configure the session scheme, add a SessionScheme element to the file. For example:
<SessionScheme name="custom_scheme">
        class="com.netegrity.proxy.session.CustomScheme"    
        accepts_smsession_cookies="false"   
        property1="value1"  
        property2="value2"  
</SessionScheme>
In addition, if you have configured user agent types, you can map the session scheme to any appropriate user agents types.
Configure Rewritable Session Schemes
If a session scheme must have the ability to modify the URL requested by a user, you must implement the rewritable interface. For example, this interface is used by the simple URL rewriting scheme to enable the session scheme to append a token to the end of URL requests.
Implement the Rewritable Interface
When implementing the rewritable interface, the following methods are available:
Return Value
Method
Description
public string
rewrite(String url, String id, HttpServletRequest req)
Rewrites a requested URL to contain a session identifier.
public string
onSessionCreateRedirect(String id, String url, HttpServletRequest req,
HttpServletResponse resp)
Provides a callback for the event of session creation by redirection. It is typically used in conjunction with forms-based authentication, where the target URL is different from the requested URL. For example, the authentication scheme may modify the URL or add a cookie.
In addition to the rewritable interface, the following methods of session scheme API must be implemented in the custom session scheme class:
Return Value
Method
Description
protected void
setRequestURI(HttpServletRequest req, String uri)
Allows the scheme to modify the request URI.
protected void
setRequestPathInfo(HttpServletRequest req, String pathInfo)
Allows the scheme to modify the path information of the request.
Use an IP Address Session Scheme
The default 
CA Access Gateway
 installation includes an IP address session scheme. This scheme maps a session using the IP address of the client. When a user makes a request, the 
CA Access Gateway
 retrieves the client’s IP address from the HTTP headers and uses this to generate the session key for the client’s session.
The IP address session scheme was created using the session scheme API. The source code for this scheme can be found in the directory 
sps_home
\secure-proxy\proxy-engine\examples\sessionschemes.
In the sample session scheme file, a backslash (\) character indicates that the line should continue, but must be interrupted due to space constraints in this document.
To implement an IP address session scheme
  1. Add a <SessionScheme> section to your server.conf file like the following:
    <SessionScheme name="ip_address">
        class="com.netegrity.proxy.session.IPAddrSessionScheme"
        accepts_smsession_cookies="false"
        allowed_proxied_addresses="true"
    </SessionScheme>
    The directives are:
    • class
      This directive specifies the Java class that handles IP address session schemes. This value should not be modified if you want to use the default IP address session scheme installed with the 
      CA Access Gateway
      .
      Default:
       com.netegrity.proxy.session.IPAddrSessionScheme
    • accepts_smsession_cookies
      Indicates that  smsession cookies are not supported by this session scheme. To ensure a cookieless session using the IP address scheme, the value of this directive should not be changed.
      Default:
       false
    • allowed_proxied_addresses
      Indicates whether or not requests will be validated using the SessionScheme.isValidRequest call. Set the value to true to allow the use of proxied addresses. Accept the default, false to use the isValidRequest method for determining if the VIA HTTP header variable is present. If this variable is present, the 
      CA Access Gateway
       determines that the address is proxied and blocks the request.
      Default:
       true
  2. Map the session scheme to one or more user agents for a virtual host in the server.conf file.
  3. Restart the 
    CA Access Gateway
    .
Session Storage API
The 
CA Access Gateway
 stores mappings from a session token to a  session. This information is accessed using the SessionStorageAPI.
The SessionStorageAPI provides the following capabilities:
  • Session creation
    Allows the creation of a new session.
  • Session update or synchronization
    Allows updates to 
    CA Single Sign-On
     session information.
  • Session retrieval
    Allows the retrieval of session information when provided with the correct session key.
  • Explicit session removal
    Allows the removal of a session using a specific session key.
  • Session expiration
    Allows the removal of all expired sessions.
Filter API Overview
Custom filters are filters defined by customer's needs. 
CA Access Gateway
 uses custom filters to manipulate a request before forwarding the request to a backend server, and also to manipulate the responses sent by the backend server to the user client.
The 
CA Access Gateway
 can process a single custom filter or a group of custom filters for each request. When you create a custom filter group, the 
CA Access Gateway
 processes all the filters that are part of the custom filter group in a chain.
You can look at the source code for a pre-processing filter and a post-processing filter produced with the filter API. These samples may be found in the following directory:
sps_home
/proxy-engine/examples/filters
In the code samples, a backslash (\) character indicates that the line should continue, but must be interrupted due to space constraints in this document.
How 
CA Access Gateway
 Processes Custom Filters
The 
CA Access Gateway
 includes an API for inserting pre-processing and post-processing into the proxy stage of a request.
In a standard  transaction, the following process occurs:
  1. User requests a resource.
  2. CA Access Gateway
     examines its proxy rules and determines where to direct the request (after successful authentication and authorization).
  3. Destination server sends the requested resource to the 
    CA Access Gateway
    , which passes the resource to the user.
The Filter API provides a method for developers to insert processing before a request is passed to a destination server, as described in step 2 of the preceding process, or after the response from the destination server is returned to the 
CA Access Gateway
 as described in step 3 of the preceding process, but before the resource is passed to the user.
For Authentication and Authorization of the Web Services, see the Configuring the Authentication and Authorization Web Services.
Associate Custom Filters to Proxy Rules
When the 
CA Access Gateway
 receives a request or a response, the 
CA Access Gateway
 reads the proxy rules and processes the associated filters. The custom filters or custom group filters that are declared in the server.conf file must be associated with proxy rules. To associate custom filters or custom group filter to proxy rules, open the proxyrules.xml located in 
<install dir>
/secure-proxy/proxy-engine/conf, edit the proxyrules.xml file for the rule that is expected to run the filter.
For example:
<nete:forward filter="
your filter name or your groupfiltername
">http://FQDN$0</nete:forward>
Filter API Class File
The 
CA Access Gateway
 Filter API makes use the proxy filter classes contained in 
sps_home
/Tomcat/server/lib/proxyrt.jar.
ProxyFilter Interface
The ProxyFilter interface defines the interface implemented by a proxy filter. However, it is recommended that you extend the BaseProxyFilter Abstract Implementation, rather than implementing the ProxyFilter interface.
The ProxyFilter interface consists of the following methods:
Return Value
Method
void
doFilter(ProxyRequest prequest, ProxyResponse presponse)
Performs the filtering.
Parameters:
request - the proxy request data
response - the proxy response data
Throws:
ProxyFilterException - thrown if failure processing filtering.
ProxyFilterConfig
getFilterConfig()
Returns this filter's ProxyFilterConfig object. (ProxyFilterConfig object that initialized this filter).
void
init(ProxyFilterConfig config)
Called when the filter is created to perform any required initialization.
Parameters:
config - a ProxyFilterConfig object containing the filters's configuration and initialization parameters
Throws:
ProxyFilterException - thrown if failure initializing this filter.
BaseProxyFilter Abstract Implementation
The Filter API includes BaseProxyFilter, an abstract implementation of a proxy filter that can be extended by a subclass to create ProxyFilters.
It is recommended that you extend the BaseProxyFilter Abstract Implementation, rather than implementing the ProxyFilter interface.
A subclass of BaseProxyFilter must override at least one of the following methods:
  • doPreFilter
  • doPostFilter
  • doFilter (not recommended)
The BaseProxyFilter includes filter initialization and separates pre-processing and post-processing hooks for inserting your own filters into 
CA Access Gateway
 transactions, as listed in the following table.
Return Value
Method
Void
doFilter(ProxyRequest prequest,
ProxyResponse presponse) throws
ProxyFilterException
This implementation determines the state of the request processing and calls doPreFilter if it's in an inbound state otherwise it calls doPostFilter for outbound state. At the time the filters get called processing can only be in one of these states.
Specified by:
doFilter in interface ProxyFilter
Parameters:
request - the proxy request data
response - the proxy response data
Throws:
ProxyFilterException - thrown if failure processing filtering
Void
doPreFilter(ProxyRequest prequest,
ProxyResponse presponse) throws
ProxyFilterException
Performs pre-filtering. Override this method to perform filtering tasks before the request is sent to the target server.
Parameters:
request - the proxy request data
response - the proxy response data
Throws:
ProxyFilterException - thrown if failure processing filtering
Void
doPostFilter(ProxyRequest prequest,
ProxyResponse presponse) throws
ProxyFilterException
Performs post-filtering. Override this method to perform filtering tasks after the response is received from the target server.
Parameters:
request - the proxy request data
response - the proxy response data
Throws:
ProxyFilterException - thrown if failure processing filtering
ProxyFilterConfig
getFilterConfig()
Returns this filter's ProxyFilterConfig object.
Specified by:
getFilterConfig in interface ProxyFilter
Returns:
ProxyFilterConfig the ProxyFilterConfig object that initialized this filter.
Void
init(ProxyFilterConfig config) throws
ProxyFilterException
Called when the filter is created to perform any required initialization.
Note:
When overriding this method, the first statement should call the parent init method "super.init(config);".
Specified by:
init in interface ProxyFilter
Parameters:
config - a ProxyFilterConfig object containing the filters's configuration and initialization parameters
Throws:
ProxyFilterException - thrown if failure initializing this filter.
ProxyFilterConfig Interface
Defines the interface to the configuration data available to a filter. The interface consists of the following methods:
Return Value
Method
java.lang.String
getFilterName()
Returns the name of this filter.
java.lang.String
getInitParameter(java.lang.String name)
Returns a String containing the value of the named initialization parameter, or null if the parameter does not exist.
Parameters:
name - a String specifying the name of the initialization parameter
java.util.Enumeration
getInitParameterNames()
Returns the names of the filter's initialization parameters as an Enumeration of String objects, or an empty Enumeration if the filter has no initialization parameters.
ProxyResponse Interface
Defines the interface that provides access to HTTP response information to be returned to the proxy client. The interface consists of the following methods:
Return Value
Method
void
addHeader(java.lang.String name, java.lang.String value)
Adds a header with the specified name and value. This method allows response headers to have multiple values.
Parameters:
name - a String specifying the header name
value - a String specifying the header value
byte[]
getContent()
Returns a byte array of the content of the response to the proxy request. This is the content to be returned to the proxy client.
java.lang.String
getHeader(java.lang.String name)
Returns the value of the specified header as a String. If the header does not exist, this method returns null. The header name is not case sensitive.
Parameters:
name - a String specifying the header name
java.util.Enumeration
getHeaderNames()
Returns an Enumeration of all the header names. If no headers exist, this method returns an empty Enumeration.
int
getStatusCode()
Returns the HTTP response status code of the response to the proxy request.
java.lang.String
removeHeader(java.lang.String name)
Removes the specified header. Returns the value of the removed header as a String. If the header does not exist, this method returns null. The header name is not case sensitive.
Parameters:
name - a String specifying the header name
void
setContent(byte[] content)
Sets the content of the response to the proxy request. This overwrites the content to be returned to the proxy client.
Parameters:
content - the byte array containing the content
void
setHeader(java.lang.String name, java.lang.String value)
Sets a header with the specified name and value. If a header with the same name exists it will be overwritten.
Parameters:
name - a String specifying the header name
value - a String specifying the header value
ProxyFilterException Class
The ProxyFilterException class defines a general exception that a filter can throw when it encounters difficulty.
Constructor Signature
Description
ProxyFilterException()
Constructs a new ProxyFilterException.
ProxyFilterException(java.lang.String message)
Constructs a new ProxyFilterException with the specified message.
Parameters:
message - Message of exception
ProxyFilterException(java.lang.String message, java.lang.Throwable rootCause)
Constructs a new ProxyFilterException with the specified message and root cause.
Parameters:
message - Message of exception
rootCause - Exception that caused this exception to be raised
ProxyFilterException(java.lang.Throwable rootCause)
Constructs a new ProxyFilterException with the specified root cause.
Parameters:
rootCause - Exception that caused this exception to be raised
ProxyRequest Interface
Defines the interface that provides access to HTTP request information to be sent by the proxy. The interface consists of the following methods:
Return Value
Method
java.lang.String
getHeader(java.lang.String name)
Returns the value of the specified header as a String. If the header does not exist, this method returns null. The header name is not case sensitive.
Parameters:
name - a String specifying the header name
java.util.Enumeration
getHeaderNames()
Returns an Enumeration of all the header names. If no headers exist, this method returns an empty Enumeration.
javax.servlet.http.HttpServletRequest
getOriginalRequest()
Returns the original HttpServletRequest made to the proxy.
java.lang.String
getSessionKey()
Returns the value of the session key as a String. If the key is not available, this method returns null. The key may be used to rewrite URL's in the content when using cookieless schemes.
Note:
The SessionScheme is responsible for creating the key and storing it in an attribute named SessionScheme.DEFAULT_SESSION_KEY_NAME
java.lang.String
getTargetQueryString()
Returns the query string the proxy will use with the target URL. The query string may be from the original request or a new one defined through the proxy rules. This method returns null if the URL does not have a query string.
java.lang.String
getTargetURL()
Returns the URL the proxy will use to make the request as defined by the proxy rules. The URL does not include query string parameters.
boolean
isInbound()
Returns a boolean value indicating the state of the request processing. If the request has not been forwarded to the target server true is returned. If the request was sent and the response received false is returned.
boolean
isOutbound()
Returns a boolean value indicating the state of the request processing. If the request has not been forwarded to the target server false is returned. If the request was sent and the response received true is returned.
java.lang.String
removeHeader(java.lang.String name)
Removes and returns the value of the specified header as a String. If the header does not exist, this method returns null. The header name is not case sensitive.
Parameters:
name - a String specifying the header name
void
setHeader(java.lang.String name, java.lang.String value)
Sets a header with the specified name and value. If a header with the same name exists it will be overwritten.
Parameters:
name - a String specifying the header name
value - a String specifying the header value
byte[]
getContent()
Returns a byte array of the content of the Request POST data. This is the content which is sent to the backend server.
void
setContent(byte[] content)
Sets the content of the POST data to the proxy request.
This overwrites the content to be sent to the backend server.
Parameters:
content - the byte array containing the request POST data
Implement a Filter
Filters that use the session key depend on the session scheme to define the key. To make the session key available to a filter, an attribute keyed by SessionScheme.DEFAULT_SESSION_KEY_NAME must be set to hold the value of the key when it is created by the createKeyFromRequest(..) callback and retrieved on subsequent requests by the getKeyFromRequest(..) callback of the Session Scheme API.
Out-of-the-box session schemes that generate the session key are:
  • Mini-cookies
  • Simple URL rewriting
Follow these steps:
  1. Review the sample code for filters in Filter Examples.
  2. Write source code for your filter.
  3. Ensure that your system CLASSPATH includes the following content:
    • proxyrt.jar which contains the filter API
    • JDK version 1.6.0_30 or higher jar files
    • sps_home
      /Tomcat/lib jar files
  4. Compile the filter.
  5. Do 
    one
     of the following steps:
    • Create a .jar file that contains your filter and copy the file to the directory 
      sps_home/
      Tomcat/lib directory.
    • Add the class files for your filter in a jar in the 
      sps_home/
      Tomcat/lib directory.
  6. Configure the 
    CA Access Gateway
     server.conf file.
  7. Edit the proxyrules.xml file for the rule that is expected to implement the filter. For example:
    <nete:forward filter="your filter name">http://FQDN$0</nete:forward>
  8. Restart the 
    CA Access Gateway
    .
Filter API Example
The 
CA Access Gateway
 installation includes sample source files for a preprocessing filter and a post-processing filter at 
installation_home
/proxy-engine/examples/filters. Both of these samples use the BaseProxyFilter Abstract Implementation. For a complete description of the example filters, see Filter Examples.
Using a Filter to Rewrite Absolute Links in a Requested Page
One of the most common uses of the Filter API is to support the rewriting of absolute links in pages requested by a user through the 
CA Access Gateway
. For absolute links to be handled properly by the 
CA Access Gateway
, you must use the Filter API to perform the appropriate substitution for any absolute links contained in resources returned to the user based on a 
CA Access Gateway
 request.