DSMLv2 SOAP Connector

Directory Integrator, Version 7.1.1

DSMLv2 SOAP Connector

The DSMLv2 SOAP Connector implements the DSMLv2 standard. The Connector is able to:

Execute DSMLv2 requests against a DSML Server.
Provide the option to use DSML SOAP binding.
Internally instantiate, configure and use the HTTP Parser to create HTTP requests and parse HTTP responses.
Internally instantiate, configure and use the DSMLv2 Parser to create DSMLv2 request messages and parse DSMLv2 response messages.

Supported Connector Modes

The Connector mode determines the type of DSML operation the Connector requests. The DSMLv2 SOAP Connector supports the following modes:

AddOnly: The DSMLv2 SOAP Connector sends DSMLv2 addRequest and receives a DSMLv2 addResponse message.
Iterator: The DSMLv2 SOAP Connector sends a DSMLv2 searchRequest operation with a Search Base, Search Filter and Search Scope taken from the current Connector configuration. The DSML server returns a DSMLv2 searchResponse message with multiple searchResultEntry elements. The Connector cycles through the DSML searchResultEntry elements and delivers each one in a separate AssemblyLine iteration.
Lookup: The DSMLv2 SOAP Connector sends a DSMLv2 searchRequest with a Search Filter constructed from the Connector's Link Criteria. The DSML server returns a DSMLv2 searchResponse message that is returned as the Entry found. If there are multiple searchResultEntry elements in the searchResponse message, you must process them in an On Multiple Entries hook.
Delete: The Connector creates and sends a DSML deleteRequest as per the Link Criteria. The DSML server returns a deleteResponse message.
Update: If the $dn Attribute in the work Entry is equal to the $dn Attribute of the Entry to be updated, the Connector sends a modifyRequest DSMLv2 request and receives a modifyResponse response; otherwise a modDnRequest request is sent to the DSML server and a modDnResponse response is received.
Delta: In Delta mode, it is the AssemblyLine that, depending on the Entry tagging, decides which Connector method to invoke and what DSMLv2 request will be sent. Delta tagging at the Attribute level is handled by the DSMLv2 Parser and delta information is incorporated into the resulting DSMLv2 request.
The DSMLv2 SOAP Connector detects in its modEntry method if the "newrdn" attribute exists and if yes it replaces the rdn in the target $dn with the new value. Then a modDnRequest request is sent to the DSML server and a modDnResponse response is received.
CallReply: In CallReply mode, the Connector provides the work Entry to the DSMLv2 Parser and sends the DSMLv2 message produced by the DSMLv2 Parser. The response from the DSMLv2 Server is passed directly to the DSMLv2 Parser, and the Entry produced is returned by the Connector. You must assign the correct request type, because the Connector will not automatically set any DSMLv2 element. In particular, the CallReply mode can be used to send DSMLv2 extended operations. See Extended Operations for more information.

In CallReply mode, the DSMLv2 SOAP Connector can send DSMLv2 extended operations. Extended operations are identified by their Operation Identifier (OIDs). For example, the OID of the extended operation for retrieving a part of the log file of the IBM Tivoli Directory Server is 1.3.18.0.2.12.22.

Extended operations can also have a value property, which is a data structure containing input data for the corresponding operation. The value property of the extended operation must be Basic Encoding Rules (BER) encoded and then base-64 encoded in the DSMLv2 message. The user of the DSMLv2 SOAP Connector is responsible only for BER encoding the value property. The Connector will automatically base-64 encode the data when creating the DSMLv2 message.

Two classes are used for BER encoding and decoding: BEREncoder and BERDecoder, located in thecom.ibm.asn1 package.

The following example illustrates sending a DSMLv2 extended operation request and the processing of the response:

Place the following script code in Output Map for attribute dsml.extended.requestvalue:

enc = new Packages.com.ibm.asn1.BEREncoder();
serverFile = 1;  //slapdErrors log file

nFirstLine = new java.lang.Integer(7200);  
nLastLine = new java.lang.Integer(7220);

seq_nr = enc.encodeSequence();
enc.encodeEnumeration(serverFile);   
   
enc.encodeInteger(nFirstLine);
enc.encodeInteger(nLastLine);

enc.endOf(seq_nr);
var myByte = enc.toByteArray();

ret.value = myByte;

Place the following script code in the After CallReply hook of the Connector:

var ba = conn.getAttribute("dsml.response").getValue(0);
bd = new Packages.com.ibm.asn1.BERDecoder(ba);

main.logmsg("SLAPD log file:");
main.logmsg(new java.lang.String(bd.decodeOctetString()));

SOAPAction Header

The DSMLv2 SOAP Connector by default always sends an empty header for the SOAPAction header. The OASIS Standard around SOAP states the this: "Each SOAP request body contains a single batchRequest. A SOAP node SHOULD indicate in the 'SOAPAction' header field the element name of the top-level element in the <body> of the SOAP request." It is valid for this header to be empty but it should optionally be something that can be set. Additionally, some vendors have defined the header to be mandatory in their DSML definitions (Sun is an example, see http://docs.oracle.com/cd/E19261-01/820-2765/6nebir7ld/index.html ).

If needed, you can set the SOAPAction Header yourself by means of the SOAPAction Header parameter.

Configuration

The DSMLv2 SOAP Connector uses the following parameters:

DSMLv2 Server URL

Specifies the URL of the DSMLv2 Server.

Authentication Method

Specifies the type of HTTP authentication. If the type of HTTP authentication is set to Anonymous, then no authentication is performed. If HTTP basic authentication is specified, HTTP basic authentication is used with user name and password as specified by the username and password parameters.

Username

The user name used for HTTP basic authentication.

Password

The password used for HTTP basic authentication.

Binary Attributes

Specifies a comma-delimited list of attributes that will be treated by the Connector as binary attributes. This parameter has the following default list of attributes that you can change:

photo
personalSignature
audio
jpegPhoto
javaSerializedData
thumbnailPhoto
thumbnailLogo
userPassword
userCertificate
authorityRevocationList
certificateRevocationList
crossCertificatePair
x500UniqueIdentifier
objectGUID
objectSid

Search Base

Specifies the starting point for searches when iterating.

Search Filter

Specifies the LDAP filter used when iterating.

Search Scope

The search scope to be used when iterating. Possible values are:

subtree
onelevel

The default is subtree.

Soap Binding

When this parameter is enabled, the Connector sends and receives SOAP DSML messages. Otherwise, the DSML messages are not wrapped in SOAP.

SOAPAction Header

The SOAPAction header value to include when SOAP binding is enabled. The default header value is empty.

Detailed Log

Turns on debug messages. This parameter is common to all Tivoli® Directory Integrator components.

IBM Tivoli Directory Integrator 7.1.1