SPMLv1 Connector

The Java-based SPML v1 SOAP connector runs inside the DirX Identity Connector Integration Framework. It sends SPML SOAP requests over HTTP to the configured endpoint and receives SPML SOAP responses from a SOAP service.

There are two flavors of the connector identified by their class name in the package siemens.dxm.connector.framework.soap:

The connector supports all SPMLv1 requests and the corresponding methods of the connector API: addRequest, modifyRequest, deleteRequest, searchRequest, extendedRequest, cancelRequest, batchRequest.

The connector supports basic authentication as well as server and client-side SSL/TLS authentication. It does not support WS-Security protocols yet.

The connector does not support connection pooling. It uses the Axis "maintainSession" feature together with a configurable time-out in order to hold connection between consecutive requests.

Prerequisites

The connector is part of the Identity Java Connector Integration Framework and uses Apache Axis1 V1.4 for sending and receiving SOAP requests and responses over HTTP. As a result, the following libraries need to be in the classpath, which are delivered together with the framework:

  • axis.jar

  • saaj-api.jar and saaj-impl.jar

  • jaxrpc-api.jar and jaxrpc-ri.jar

  • saaj-api.jar and saaj-impl.jar

  • commons-discovery.jar

  • commons-logging.jar

Configuration

The connector receives its configuration by the connector framework in a format that is specified there and reflects an XML document. Note that Identity Manager presents configuration options in a more convenient manner. Especially bind credentials, SSL flag and service address are typically collected from appropriate LDAP entries found by selecting the appropriate connected directory and bind profile.

The following discusses the configuration options based upon the XML format. These options are either specified attributes in the XML schema of the element <connection> (referred to as standard properties) or may be specified as <property> sub-elements of the <connection> element (referred to as non-standard properties).

The connector evaluates the following standard and non-standard properties:

Standard attributes:

url

(optional) The endpoint where to send the request;

for example, http://localhost:8080/spml/spmlservice.

You either need to specify the SOAP endpoint completely in this url parameter or provide the parts in the attributes server, port, ssl and the non-standard property path.

A protocol selector of "https" requests SSL/TLS protocol. In this case, you must ensure that the certificate of the addressed Web server is imported in the trust store of the Java runtime. See the JDK documentation (keytool) for details.
server

(optional) If no url is given, this property provides the server part of the url. In the above sample, this would be "localhost".

port

(optional) If no url is given, this property provides the port of the url. In the above sample, this would be "8080".

ssl

(optional) If no url is given, this property tells the connector which protocol to use. If true, https is selected. Otherwise, the connector sets http. In the above sample, a missing ssl property or the value false would apply.

user

(optional) the user name used for HTTP basic authentication.

password

(optional) the password used for HTTP basic authentication.

trustStore

(optional) the path to the trust store file, which contains the certificate of the server to be used for SSL/TLS server-side authentication.

trustStorePassword

(optional) the password that is required to read the certificate from the trust store.

keyStore

(optional) the path to the key store file that contains the private key or certificate to be used for SSL/TLS client authentication.

keyStorePassword

(optional) the password that is needed to read the key from the key store.

keyStoreAlias

(optional) the alias name to identify the private key in the key store.

The SOAP connector evaluates the following non-standard properties beneath the <connection> element:

maintainSession

(optional) boolean (true / false); if set to "true" (the default), maintains the HTTP session to the target Web service between consecutive requests and thereby saves performance.

path

(optional) If no url is given, this property provides the path of the url. In the above sample, this would be "spml/spmlservice".

timeout

(optional) The socket timeout in seconds. Default is 60.

includePrefixesForXsdPrimitiveTypes

(optional) boolean (true / false); if set to "false" (the default), the DSML value types are not declared with full XML name. Only the XML attribute type is declared and a common string is used as its value.

httpHeaders

(optional) multi-value string in the format "*httpHeaderName httpHeaderValue"* (for example "X-Requested-With XMLHttpRequest"); if set, each SOAP request sent over HTTP will contain additionally these custom HTTP headers. Note that a custom HTTP header name and its value must be separated by a space.

Here is a configuration sample using the url property to denote the SOAP endpoint using the SPMLv1 compliant connector implementation:

<connector    role="connector" className="siemens.dxm.connector.framework.soap.DxaSpmlSoapProxy"
        name="SPML connector">
    <connection type="SOAP"
        url="http://localhost:8080/spmlsoapservice/services/SpmlSoapService"
    />
</connector>

The following is an alternative with the non-compliant SPML connector class using the properties server, port, path and ssl to denote the SOAP endpoint.

    <connector  role="connector" className="siemens.dxm.connector.framework.soap.SpmlSoapProxy"
name="SoapConnector">
<connection type="SOAP"
   server="localhost" port="8080" ssl="false"
>
   <property name="path" value="spmlsoapservice/services/SpmlSoapService"/>
</connection>
</connector>