Administration Guide › Using CA SiteMinder® SPS APIs

Using CA SiteMinder® SPS APIs

This section contains the following topics:

Session Scheme API

The CA SiteMinder® SPS 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 SiteMinder® SPS.

Overview of Session Scheme API Processing

The CA SiteMinder® SPS 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 Rewritable Session Schemes.

The following illustration shows the process flow for the session scheme API methods.

The methods identified in the illustrated are:

isValidRequest—This method must be implemented in a custom session scheme to determine and verify the conditions that make up a valid request.
getKeyFromRequest—This method must be implemented to extract a key from a valid request. If no key is present, the createKeyFromRequest method is called.
createKeyFromRequest—This method must be implemented to trigger the creation of a key for a new session.
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.
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.
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.
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 SiteMinder® SPS 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 SiteMinder’s 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 SiteMinder 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.
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.
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:

Review the sample code for the IP address session scheme in IP Address Session Scheme.
Write source code for your session scheme.
If you are creating a rewritable session scheme, implement the rewritable interface.
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
Compile the session scheme.
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 SiteMinder® SPS server.conf file.
Restart the CA SiteMinder® SPS.

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 SiteMinder® SPS 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 methods must be implemented in the custom session scheme.

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 SiteMinder® SPS 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 SiteMinder® SPS 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.

Note: 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

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 SiteMinder® SPS.

Default: com.netegrity.proxy.session.IPAddrSessionScheme

accepts_smsession_cookies

Indicates that SiteMinder 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 SiteMinder® SPS determines that the address is proxied and blocks the request.

Default: true
Map the session scheme to one or more user agents for a virtual host in the server.conf file.
Restart the CA SiteMinder® SPS.

Session Storage API

The CA SiteMinder® SPS stores mappings from a session token to a SiteMinder 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 SiteMinder 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 SiteMinder® SPS 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 SiteMinder® SPS can process a single custom filter or a group of custom filters for each request. When you create a custom filter group, the CA SiteMinder® SPS 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

Note: In the code samples, a backslash (\) character indicates that the line should continue, but must be interrupted due to space constraints in this document.

More Information

Associate Custom Filters to Proxy Rules

How CA SiteMinder® SPS Processes Custom Filters

The CA SiteMinder® SPS includes an API for inserting pre-processing and post-processing into the proxy stage of a request.

In a standard CA SiteMinder® SPS transaction, the following process occurs:

User requests a resource.
CA SiteMinder® SPS examines its proxy rules and determines where to direct the request (after successful authentication and authorization).
Destination server sends the requested resource to the CA SiteMinder® SPS, 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 SiteMinder® SPS as described in step 3 of the preceding process, but before the resource is passed to the user.

Associate Custom Filters to Proxy Rules

When the CA SiteMinder® SPS receives a request or a response, the CA SiteMinder® SPS 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 SiteMinder® SPS 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.

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 implemented as a subclass to create ProxyFilters.

Note: 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 SiteMinder® SPS 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.

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 message and 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:

Review the sample code for filters in Filter Examples.
Write source code for your filter.
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
Compile the filter.
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.
Configure the CA SiteMinder® SPS server.conf file.
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>
Restart the CA SiteMinder® SPS.

Filter API Example

The CA SiteMinder® SPS installation includes sample source files for a preprocessing filter and a post-processing filter. 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 SiteMinder® SPS. For absolute links to be handled properly by the CA SiteMinder® SPS, 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 SiteMinder® SPS request.