Introduction

Ceptor offers a WebService/XML integration service which integrates the functionality of Ceptor into other security solutions. This allows other security solutions to securely access the extensive suite of services available internally in the Ceptor security infrastructure. This includes gaining access to, for example, shared sessions, central logging, extensive statistics and application server security plug-ins.
This document describes how to integrate the other security solutions with Ceptor through the WebService/XML integration interface.
This document will not describe how to install and configure Ceptor components/agents in general. For more information about these issues please refer to the Ceptor documentation and white papers.

Integration Services

The WebService/XML integration service offers the possibility for an external security solution to create and manipulate sessions through the Ceptor session controller(s). Through the integration service it is also possible to utilize the central logging and statistics features in Ceptor.
Below are listed the methods available through the WebService/XML integration interface:

WebService/XML integration interface

• CreateSession
  Creates a session in the Ceptor domain (essentially log a user in) allowing for shared sessions across backend applications and enables usage of, for example, Ceptor application server plugins. Sessions can be created as anonymous or logged in sessions.
• LoginSession
  Sets the session state to "logged in" if the session created was anonymous or the session has been logged off.
• LogoffSession
  Sets the session state to "logged off"
• RemoveSession
  Remove a session from the Ceptor plugin (essentially log the user off the Ceptor domain).
• SetSessionAttribute
  Sets a session attribute in the Ceptor session allowing backend applications to read that information.
• GetSessionAttribute
  Retrieves a session attribute from the Ceptor shared session.
• LogStatistics
  Log statistic values in the central Ceptor statistics repository.
• LogToTransactionLog
  Adds a log entry to the transaction log in Ceptor.

Using these methods an external security solution can create a session through Ceptor when the user accesses the system. Each of these methods corresponds to a method in the Ceptor agent API and the list of methods can easily be expanded upon request.

Integration Architecture

A complete Ceptor installation could be implemented like this.

When using the Ceptor integration service, the dispatcher agent and tunnels are usually not used (this service is handled by the external security provider). Also the user authentication and authorization directory integration feature in Ceptor is likely not to be used since this information is derived from the external security provider, though it is possible for the external security provider to share its data with Ceptor allowing for the existing Ceptor authorization plugins to access this information. When using an external security provider the architecture will look slightly different.

The architectural difference is that the Ceptor dispatcher/reverse proxy agent is not used (this is the agent in Ceptor that ensures session handling and user authentication/autorization). Also the session controller(s) configuration will be simpler by not including authentication plugins for different authentication methods since this is handled by the external security provider. The Ceptor session controller(s) could be configured to utilize an autorization repository provided by the external security solution. This would allow Ceptor to build and use already existing complex group/ACL structures instead of having the external security solution parse them to the session controller(s) when logging a user in. If the external security solution only provides a simple list of groups for the individual users, these can be pasrsed to the session controller(s) when the user has been authenticated.

Using the Integration Service

The integration service can be used as a WebService (utilizing SOAP 1.1) or through an XML interface via HTTP. There is no difference in the two ways of accessing the integration service except that the XML interface offers higher performance. The two interfaces will always offer the same services with the same arguments. Using a standard SOAP implementation (like for example Apache Aaxis that offers both Java and C/C++ implementations) allows for a very fast integration between the external security solution and Ceptor. The XML interface will require more work to implement but the performance gained (especially in a high volume environment) might be worth considering.
Both services are accessed through the session controller(s).

The WebService Interface

The WebService interface can be reached by accessing the session controllers with the following URL: http://controllerip:controllerport/pp/integrationservice.jws. This WebService definition can be automatically fetched by accessing http://controllerip:controllerport/pp/integrationservice.jws?wsdl. This will return the WSDL as needed for accessing that particular session controller.

A Sample SOAP Request

Creating a session based on the WSDL returned from the integration service would happen by sending a SOAP message like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:createSession soapenv:encoding
			Style="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="http://DefaultNamespace">
			<ip xsi:type="xsd:string">127.0.0.1</ip>
			<userid xsi:type="xsd:string">used_id</userid>
			<groups xsi:type="xsd:string">group_1,group_2,group_3</groups>
		</ns1:createSession>
	</soapenv:Body>
</soapenv:Envelope>

This would make the session controller create a session and log the user in based on the user with the user id "user_id" coming from ip address "127.0.0.1" giving him access to 3 groups (namely group_1, group_2 and group_3). If an anonymous session is required the user id and group listing can be left out (null values are allowed).

In response to the above request the session controller will return the following SOAP response.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:createSessionResponse
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<createSessionReturn xsi:type="xsd:string">6253847154648596a6fba7e82d82d9a9</createSessionReturn>
		</ns1:createSessionResponse>
	</soapenv:Body>
</soapenv:Envelope>

This states that a new session with the session id "6253847154648596a6fba7e82d82d9a9"was created and the user was successfully logged in. If an error occures during session creation, for example if invalid arguments where given or the session controller is not configured correctly, a response looking like the following will be returned.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<soapenv:Fault>
			<faultcode>soapenv:Server.userException</faultcode>
			<faultstring>dk.itp.security.passticket.PTException:
Unable to create session, ip address 27.0.0.1 is restricted</faultstring>
			<detail>
				<ns1:hostname xmlns:ns1="http://xml.apache.org/axis/">SESSIONSRV</ns1:hostname>
			</detail>
		</soapenv:Fault>
	</soapenv:Body>
</soapenv:Envelope>

This example states that the session could not be created due to IP address restrictions.
After creating a session the external security solution must parse the Ceptor session ID in a cookie to the backend application servers in order for the applications and the Ceptor agents to work correctly. The default cookie name is "sclSessionID".Depending on the type of application server the session id is added to the HTTP request either as a cookie or in a basic authentication header.

Configuring the WebService Interface

WebService Configuration Issues

The Ceptor WebService interface is built using the Apache Axis framework. When the Ceptor session controller has been installed and enabled for using the WebService integration interface it runs "as is" with no further configuration.
Since the Ceptor Webservice interface is built on the Axis framework it is possible to manipulate the WebService configuration. This allows for enabling SOAP monitoring using the Axis SOAP monitor, enabled security for the WebService calls (it is for example possible to use the Axis support for HTTP based security and userid/password through the SOAP header). This is all done through the "server-config.wsdd" deployment descriptor.
It is also possible to set up security through the web application deployment descriptor, depending on the application server used to run the Ceptor session controller, this can be done through the application server configuration.
For more information on how to set up security, debug and other Axis specific features please refer to http://ws.apache.org/axis/java/index.html.
As part of the Ceptor release is a default server-config.wsdd file that supports the Ceptor integration services. This file must be built into the Ceptor server web application along with the Axis requires libraries. IT-Practice will provide such a sample build when acquiring the WebService integration feature for Ceptor. The required (and tested) libraries are:

 axis.jar
 commons-discovery-0.2.jar
 commons-logging-1.0.4.jar
 jaxrpc.jar
 saaj.jar
 wsdl4j-1.5.1.jar 

Next the WEB.XML needs to be updated with the appropriate Axis features. The standard features to insert could looks like this.

<servlet>
  <servlet-name>AxisServlet</servlet-name>
  <display-name>Apache-Axis Servlet</display-name>
  <servlet-class>
    org.apache.axis.transport.http.AxisServlet
  </servlet-class>
</servlet>
. . . .
<servlet-mapping>
  <servlet-name>AxisServlet</servlet-name>
  <url-pattern>/webservices</url-pattern>
</servlet-mapping>
<servlet-mapping>
  <servlet-name>AxisServlet</servlet-name>
  <url-pattern>*.jws</url-pattern>
</servlet-mapping>
<servlet-mapping>
  <servlet-name>AxisServlet</servlet-name>
  <url-pattern>/services/*</url-pattern>
</servlet-mapping>
. . .
<mime-mapping>
  <extension>wsdl</extension>
  <mime-type>text/xml</mime-type>
</mime-mapping>
<mime-mapping>
  <extension>xsd</extension>
  <mime-type>text/xml</mime-type>
</mime-mapping>

The Axis administration features will not be enabled using the standard options above. For more information on how to enable these servlets and features, please refer to the Axis documentation.

Service Samples and Definitions

This section contains service definitions and SOAP examples for all the available WebService integration services. The XML definitions will be documented at a later time.are not documented here but are available on request.

CreateSession

This service creates a session in the Ceptor domain. The session can either be created as an anonymous session or as a logged in session depending on the parameters given. If the user_id parameter is omitted or empty the session will be created as an anonymous session and the groups parameter will be ignored.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
	<soapenv:Body>
		<ns1:createSession soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<ip xsi:type="xsd:string">127.0.0.1</ip>
			<userid xsi:type="xsd:string">user_id</userid>
			<groups xsi:type="xsd:string">group_1,group_2,group_3</groups>
		</ns1:createSession>
	</soapenv:Body>
</soapenv:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:createSessionResponse
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<createSessionReturn xsi:type="xsd:string">72645ab498fed73c2940a8475c327e9832d28</createSessionReturn>
		</ns1:createSessionResponse>
	</soapenv:Body>
</soapenv:Envelope> 

LoginSession

With this service, an anonymous session can be logged in, giving the user_id and the groups' parameters. If the user_id parameter is omitted or empty, a fault will be generated.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:loginSession soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<sessionid xsi:type="xsd:string">72645ab498fed73c2940a8475c327e9832d28</sessionid>
			<userid xsi:type="xsd:string">user_id</userid>
			<groups xsi:type="xsd:string">group_1,group_2,group_3</groups>
		</ns1:loginSession>
	</soapenv:Body>
</soapenv:Envelope> 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:loginSessionResponse
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace" />
	</soapenv:Body>
</soapenv:Envelope> 

LogToTransactionLog

This service allows for logging to the Ceptor transaction log.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:logToTransactionLog
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<sessionid xsi:type="xsd:string">72645ab498fed73c2940a8475c327e9832d28</sessionid>
			<context xsi:type="xsd:string">User logged in</context>
			<text xsi:type="xsd:string">Logged in user: user_id</text>
		</ns1:logToTransactionLog>
	</soapenv:Body>
</soapenv:Envelope> 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:logToTransactionLogResponse
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace" />
	</soapenv:Body>
</soapenv:Envelope> 

SetSessionAttribute

With this service it is possible to set an attribute on a session. Session attributes are shared in the entire Ceptor domain and will be accessible to backend application servers and agents.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:setSessionAttribute
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<sessionid xsi:type="xsd:string">72645ab498fed73c2940a8475c327e9832d28</sessionid>
			<attribute xsi:type="xsd:string">name</attribute>
			<value xsi:type="xsd:string">John Doe</value>
		</ns1:setSessionAttribute>
	</soapenv:Body>
</soapenv:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:setSessionAttributeResponse
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace" />
	</soapenv:Body>
</soapenv:Envelope> 

GetSessionAttribute

Through this message it is possible to retrieve a session attribute from a Ceptor session.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:getSessionAttribute
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<sessionid xsi:type="xsd:string">72645ab498fed73c2940a8475c327e9832d28</sessionid>
			<attribute xsi:type="xsd:string">name</attribute>
		</ns1:getSessionAttribute>
	</soapenv:Body>
</soapenv:Envelope> 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:getSessionAttributeResponse
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<getSessionAttributeReturn xsi:type="xsd:string">John
				Doe</getSessionAttributeReturn>
		</ns1:getSessionAttributeResponse>
	</soapenv:Body>
</soapenv:Envelope> 

LogStatistics

This service allows for the logging of statistic values to the central statistics repository. Statistic values can be viewed and analyzed through the Ceptor administration interface along with other statistics from the Ceptor domain.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:logStatistics soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<statisticsName xsi:type="xsd:string">security.http.passthrough</statisticsName>
			<time xsi:type="xsd:long">16</time>
		</ns1:logStatistics>
	</soapenv:Body>
</soapenv:Envelope> 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:logStatisticsResponse
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace" />
	</soapenv:Body>
</soapenv:Envelope>

LogOffSession

Logs the user s aout of a session off. If the session is not currently logged on no fault will be generated.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:logoffSession soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<sessionid xsi:type="xsd:string">72645ab498fed73c2940a8475c327e9832d28</sessionid>
		</ns1:logoffSession>
	</soapenv:Body>
</soapenv:Envelope>  

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:logoffSessionResponse
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace" />
	</soapenv:Body>
</soapenv:Envelope>

RemoveSession

This service logs off and removes a session from the Ceptor domain. In general, it is not necessary to do this since the Ceptor domain Session Controller will timeout the session by itself.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:removeSession soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace">
			<sessionid xsi:type="xsd:string">72645ab498fed73c2940a8475c327e9832d28</sessionid>
		</ns1:removeSession>
	</soapenv:Body>
</soapenv:Envelope> 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soapenv:Body>
		<ns1:removeSessionResponse
			soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
			xmlns:ns1="http://DefaultNamespace" />
	</soapenv:Body>
</soapenv:Envelope>