DSML Version 2
This appendix covers:
•DSML introduction
•IBM DSML V2 service implementation
•IBM DSML V2 service installation, configuration and execution.
•Java programming examples on DSML
By the end of this appendix, you will better understand the answers to the following issues:
•What is DSML?
•Why use DSML?
•What is the difference of DSML and LDAP?
•How does IBM support DSML V2 in IBM Directory Server?
•What DSML structure and operations does IBM support?
•How to install, configure, debug and execute IBM DSML service in IBM Directory Server?
•How to program functions that execute DSML operations in Java?
DSML Version 2 Introduction
This section provides an introduction to the history of DSML, the different DSML versions and their differences.
DSML
Directory Services Markup Language (DSML) is an XML for representing directory information. It is a generic import/export format for directory information. Directory information in DSML can be shared between DSML-aware applications without exposing the LDAP protocol.
XML provides an effective way to present and transfer data; Directory services allow you to share and manage data, and are thus a necessary prerequisite for conducting online business; DSML is designed to make directory service more dynamic by employing XML. DSML is an XML schema for working with directories, it is defined using a Document Content Description (DCD). Thus, DSML allows XML programmers to access LDAP-enabled directories without having to write to the LDAP interface or use proprietary directory-access APIs, and provides one consistent way to work with multiple dissimilar directories.
DSML Version 1.0
DSML V1.0 was released at the end of 1999, it only provides a meta expression of directory data model and structure, and it has a lack of support for querying and updating operations to directories. In order to do queries or updates with DSML V1.0, a DSML/LDAP tool is needed such as Active Directory Services Interfaces, or dsmltools which is a set of Java utilities for handling DSML v1.0 data, such as querying LDAP directory with query result in DSML format, import DSML data into LDAP directory (For more information, please refer to the Web site (http://www.dsmltools.org).
DSML Version 2.0
DSML v2.0 was released in 2001, it provides a method for expressing directory queries, updates, and results of these operations in XML format. This version becomes more useful for most programmers.
DSML Version 2 URN
The base URN for DSML Version 2 is:
urn:oasis:names:tc:DSML:2:0:core
This URN provides the core namespace consisting of the individual operations and responses, a request envelope, a response envelope and an envelope grouping the entries, references and result of a search operation.
See Example A-1 on how to use the DSMLv2 URN.
Example: A-1 Using the DSML Version 2 URN
<xml:batchRequest xmlns:dsml=”urn:oasis:names:tc:DSML:2:0:core”>
DSML v2 is not required to be a strict superset of DSML v1, but it is desirable for DSML v2 to follow the design of DSML v1 where possible.
Difference between DSML v1 and DSML v2
DSML v1 represents LDAP directories in XML, represents the 'state' of a directory.
DSML v2 represents the 'operation' that an LDAP directory can perform and the result of such operations.
Difference between DSML v2 and LDAP
The following represents the differences between DSML Version 2 and LDAP:
•Authentication: LDAP request contains authentication, DSML request is not used to authenticate the requestor. This is because that a DSML v2 document can be transported via a variety of mechanisms. But it does not mean that DSML v2 cannot be used to authenticate the requestor, in fact, DSML v2 includes an Auth request that MAY be used to associate a security principal with a collection of DSML v2 operations.
•Grouping operations: LDAP does not include a method of grouping operations to be expressed in a single request. DSMLv2 can group multiple LDAP operations to be expressed in one request document. DSML v2 specifies a simple positional correspondence between individual requests within a request document and individual responses within a response document.
•DSMLv2 eliminates a redundant level of nested element, the LDAPMessage, that is caused by the systematic translation of RFC 2251.
•Defaulting: DSMLv2 uses defaulting in a few places where LDAP does not, this is because defaulting works more naturally in XML documents than in ASN.1 structures. In DSMLv2 the string-valued elements matchedDN and errorMessage (from LDAPResult in LDAP) and attributes (from SearchRequest in LDAP) are optional and the default values are empty string. The sizeLimit, timeLimit, and typesOnly elements (from SearchRequest in LDAP) have default value as 0, 0, and FALSE respectively.
Typical DSML Transaction
A typical DSML transaction contains the following steps:
1. XML application sends DSML query across HTTP network.
2. DSML Service receives the query and translates into LDAP query.
3. DSML Service retrieves data from directories, and translate back into DSML format.
4. DSML Service sends the query result back to the XML application cross the HTTP network.
See Figure A-1 for a representation of these steps.
Figure A-1 Steps for a typical DSML transaction
DSML Version 2 - IBM implementation
This section discusses IBM’s Implementation of DSML Version 2.
ITDS DSML Version 2 support
IBM Directory Server DSML v2 support extends the reach of the directory to Web services. Expose the directory and deliver it to Web services through XML coding. An enterprise's customers could, for example, make changes to directory data such as phone numbers or street addresses themselves over the Internet rather than calling in to customer service.
ITDS DSML Version 2 support includes the following implementation:
•IBM DSML Server: It provides DSML service to receive DSML request from users, executes DSML operations in LDAP server and sends DSML response back to the users.
•IBM DSML Client: It is used by users to submit DSML requests.
•IBM DSML structure, LDAP schema definition in DSML, request and response association, and supported DSML operations.
•IBM DSML bindings.
•IBM DSML communication between the two major IBM directory products: ITDI and ITDS.
IBM DSML Server
IBM's DSML Server provides two basic components: SOAP binding component and file binding component. A binding defines how the DSML v2 XML fragments are sent as request and responses in the context of a specific transport such as SOAP, SMTP, or a simple data file.
•The SOAP binding component allows user to submit a SOAP request over HTTP protocol. It must be deployed within an Apache SOAP v2.3 webapp. The DSML v2 'server' is a servlet in Servlet/JSP engine in the application server. See Figure A-2 for the SOAP binding component flow.
Figure A-2 SOAP binding component flow
Note that it is also feasible to convert DSML to HTTP using XSLT, and to inject it into the Web-based application flow.
•File binding component: allows a user to submit a request via XML input file. It resides on the same computer as the client, and is invoked by the DsmlFileClient. The DSML v2 'server' is a command-line program, as is typical for LDIF. The client invokes the 'server' program runs on the same computer as the server, and the input and output of the server are files consisting of DSML v2 documents. The DSML v2 server uses LDAP to communicate with the LDAP server. See Figure A-3 on page 640 for the file binding component flow.
Figure A-3 File binding component flow
IBM's DSML Server installation requires a servlet-supporting application server such as WebSphere Application Server, Apache SOAP v2.3. To use DSML, Java 1.3.1 is required.
DsmlSoap Client
It is used to submit an SOAP request, the SOAP request is an XML file containing a BatchRequest to an LDAP server. The SOAP server is specified by a URL provided in a command line argument at runtime.
DsmlFile Client
It is used to submit an XML file containing a BatchRequest to an LDAP server via a DSML server sitting on the same machine as the client. Both the client and server are contained in dsml.jar, therefore, this requirement should always be satisfied.
IBM DSML Version 2 top-level structure
There are two types of DSMLv2 document: The request document and the response document. In a DSMLv2-based interaction between a client and a server there is a pairing of requests and responses: For each request document submitted by the client there is one response document produced by the server.
The top-level elements of a request fragment is a BatchRequest which contains zero, one, or many individual request elements, and the top-level elements of a response fragment is a BatchResponse which consists of zero, one or many individual response elements.
Such a batch request-response pair can be used to verify that a server is capable of processing DSMLv2 documents.
Defining directory schema in DSML
DSML also can define directory schemas, and store schema information for both object classes and attribute types. This is very useful when you want to create any unavailable schemas.
DSML object classes
See Example A-2 for the DSML schema definition for person object class.
Example: A-2 DSML schema definition for person object class
<dsml:dsml xmlns:dsml="http://www/dsml.org/dsml">
<dsml:directory-schema>
<dsml:class id="person" superior="#top" type="structural">
<dsml:name>person</dsml:name>
<dsml:description>Person as defined in RFC2256</dsml:description>
<dsml:object-identifier>2.5.6.6</dsml:object-identifier>
<dsml:attribute ref="#sn" required="true"/>
<dsml:attribute ref="#cn" required="true"/>
<dsml:attribute ref="#userPassword" required="false"/>
<dsml:attribute ref="#telephoneNumber" required="false"/>
<dsml:attribute ref="#seeAlso" required="false"/>
<dsml:attribute ref="#description" required="false"/>
</dsml:class>
... ...
</dsml:directory-schema>
</dsml:dsml>
This DSML schema definition of person object class is equivalent to the 'person' object class definition in RFC2256:
(2.2.5.6 NAME 'person' SUP top STRUCTURAL MUST (sn $ cn ) MAY (userPassword $ telephoneNumber $ seeAlso $ description))
DSML attribute types
See Example A-3 for the DSML schema definition for telephoneNumber attribute.
Example: A-3 DSML schema definition for telephoneNumber attribute
<dsml:directory-schema>
<dsml:attribute-type id="telephoneNumber">
<dsml:name>telephoneNumber</dsml:name>
<dsml:description>telephone Number from RFC2256</dsml:description>
<dsml:object-identifier>2.5.4.20</dsml:object-identifier>
<dsml:syntax bound="32">1.3.6.1.4.1.1466.115.121.1.50</dsml:syntax>
<dsml:equality>telephoneNumberMatch</dsml:equality>
<dsml:substring>telephoneNumberSubstringMatch</dsml:substring>
</dsml:attribute-type>
</dsml:directory-schema>
This DSML schema definition of telephoneNumber attribute is equivalent to the 'telephoneNumber' attribute definition in RFC2256:
(2.5.4.20 NAME 'telephoneNumber' EQUALITY telephoneNumberMatch SUNSTR telephoneNumberSubstringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.50(32))
Request and response association
The client and server associate an individual response in a BatchResponse with the corresponding individual request in a BatchRequest using one (or both) of the following methods: positional correspondence or RequestID.
In a positional correspondence, the nth response element corresponds to the nth request element.
See Example A-4 for a valid batch request-response pair using positional correspondence.
Example: A-4 Valid batch request-response pair using positional correspondence
DSMLv2 Request Document:
<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyRequest>...</modifyRequest>
<addRequest>...</addRequest>
<delRequest>...</delRequest>
<addRequest>...</addRequest>
</batchRequest>
DSMLv2 Response Document:
<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyResponse>...</modifyResponse>
<addResponse>...</addResponse>
<delResponse>...</delResponse>
<addResponse>...</addResponse>
<addResponse>...</addResponse>
</batchResponse>
The alternative to positional correspondence is the use of the optional requestID attribute. When the client specifies a value for requestID in a request (for example, in an addRequest), the server MUST return the same value in the corresponding response (for example, in an addResponse). The client need not specify a requestID when positional correspondence is also used, although in some cases it may find this useful. For example, when using the file binding for a large file, some clients may find it more convenient to associate failed responses with requests using requestID rather than position.
A client must not send a request with requestID="0", as this value is reserved for unsolicited notifications.
A BatchRequest element may contain the optional XML-attribute responseOrder, which influences how the server orders individual responses within the BatchResponse. The valid values are ordered and unordered. If this attribute is omitted, the default value is ordered.
In a BatchRequest with responseOrder="ordered", the server MUST return a BatchResponse in which the individual responses maintain a positional correspondence with the individual requests.
Syntax errors
If the server detects the syntax error from the request document before performing any directory operations on behalf of the client, the response will look like Example A-5.
Example: A-5 Response to a syntax error in request document
<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<errorResponse type="malformedRequest">
<message>Unknown element 'bogusRequest' line 87 column 4</message>
</errorResponse>
</batchResponse>
The errorResponse element contains details about the error.
If the server performs one or more directory operations on behalf of the client before detecting the syntax error, the server's response contains the response element for each operation that it performed, followed by an errorResponse element. See Example A-6.
Example: A-6 Response to a syntax error after performing directory operations
DSML v2 request containing the syntax error:
<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyRequest>...</modifyRequest>
<addRequest>...</addRequest>
<bogusRequest>...</bogusRequest>
<addRequest>...</addRequest>s
...
</batchRequest>
DSML v2 reponse to syntax error in request:
<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyResponse>...</modifyResponse>
<addResponse>...</addResponse>
<errorResponse type="malformedRequest">
<message>Unknown element 'bogusRequest' line 87 column 4</message>
</errorResponse>
</batchResponse>
Failures
A client may produce a request document that is syntactically correct but that contains a request that fails when the provider executes it. Failure is defined as follows:
•The DSMLv2 provider was unable to connect to a server (represented as an errorResponse with type="couldNotConnect").
•The DSMLv2 provider connected to a server, but the server closed the connection without responding to the request (represented as an errorResponse with type="connectionClosed").
•The server returned an LDAPResultCode other than 0 ("success"), 6 ("compareTrue"), 5 ("compareFalse"), or 10 ("referral").
When a request execution fails, the server does not attempt to execute later requests within the document. The server produces a response element for each request element that was attempted, including the one that failed.
See Example A-7 for a DSMLv2 request that contains a request that fails.
Example: A-7 DSML v2 request that contains a request that fails
DSMLv2 Request containing a request that fails:
<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyRequest>...</modifyRequest>
<addRequest>...</addRequest>
<delRequest>...</delRequest>
<addRequest>...</addRequest>
</batchRequest>
DSMLv2 Response - One request not attempted:
<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyResponse>...</modifyResponse>
<addResponse>...</addResponse>
<errorResponse type="connectionClosed"/>
</batchResponse>
Parallel processing
A BatchRequest element MAY contain the optional XML-attribute processing, which influences how the server can process the request elements. The valid values are sequential and parallel. If this attribute is omitted, the default value is sequential.
See Example A-8 for BatchRequest that uses parallel processing.
Example: A-8 batchRequest definition using the parallel processing attribute
<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core" processing="parallel">
...
</batchRequest>
In a BatchRequest with processing="sequential", the server must preserve sequential semantics, that is, it behaves as already described regardless of the value of the responseOrder attribute. The effect of processing the BatchRequest must be as if the request elements were executed in the order they occur within the envelope.
In a BatchRequest with processing="parallel", the server MAY execute the request elements in any order. This form of processing is useful when a request contains multiple updates and the client knows that the updates are independent, as might be the case when DSMLv2 is used to bulk-load a directory. It is also useful when a request contains multiple queries and no updates.
In a BatchRequest with processing="parallel" and responseOrder="unordered", the client MUST specify a unique requestID for each individual request in the envelope. In this case, the server MAY return the responses in any order within the BatchResponse envelope; for example, in the order in which the operations complete, to improve server efficiency. If the client fails to specify a requestID for each request, the server MUST return an errorResponse with type="malformedRequest".
Resuming on error
A BatchRequest element MAY contain the optional XML-attribute onError, which influences how the server responds to failures while processing request elements. The valid values are: exit and resume. If this attribute is omitted, the default value is exit.
See for a batchRequest definition that contains the onError attribute.
Example: A-9 batchRequest definition using the onError attribute
<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core" onError="resume">
...
</batchRequest>
In a BatchRequest with onError="exit", the server stops executing request elements as soon as one request element fails, and the response that is sent implicitly includes a notAttempted response for all requests that do not otherwise have a response.
If processing="parallel" and onError="exit", the server stops initiating execution of new request elements as soon as one request element fails.
If the provider does not attempt to execute a request element, but needs to provide a response in order to maintain positional correspondence, it generates an errorResponse with type="notAttempted", as shown in Example A-10.
Example: A-10 errorResponse with type=”notAttempted”
DSMLv2 Request with parallel execution containing a request that fails:
<batchRequest xmlns="urn:oasis:names:tc:DSML:2:0:core"
processing="parallel" onError="resume">
<modifyRequest>...</modifyRequest>
<addRequest>...</addRequest>
<delRequest>...</delRequest>
<addRequest>...</addRequest>
</batchRequest>
DSMLv2 Response - two requests not successful
<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyResponse>...</modifyResponse>
<errorResponse type="notAttempted"/>
<delResponse>
<resultCode code="32" descr="noSuchObject"/>
</delResponse>
</batchResponse>
In a BatchRequest with onError="resume", the server executes the remaining request elements even though one or more requests have failed. This form of processing is most useful when processing="parallel".
IBM DSML LDAP Operations
This section discusses IBM DSML LDAP Operations.
ITDS DSML Request Structure
With the exception of extendedRequest, each individual request element contains:
•A dn attribute (as in DSMLv1) containing a distinguished name.
•Zero or more control elements representing LDAP Controls.
See Example A-11for a few examples of LDAP request elements.
Example: A-11 LDAP request elements
<batchRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:oasis:names:tc:DSML:2:0:core">
<modifyRequest dn="CN=Joe Smith, OU=Dev, DC=Example, DC=Com">
...
</modifyRequest>
<addRequest dn="OU=Sales,DC=Example, DC=Com">
...
</addRequest>
<delRequest dn="CN=Alice,OU=HR,DC=Example,DC=Com">
<control>...</control>
<control>...</control>
</delRequest>
<searchRequest>
<control>...</control>
...
</searchRequest>
</batchRequest>
See Example A-12 for an example of an LDAP Control.
Example: A-12 LDAP Control
<control type="1.2.840.113556.1.4.619" criticality="true">
<controlValue
xsi:type="xsd:base64Binary">RFNNTHYyLjAgcm9ja3MhIQ==
</controlValue>
</control>
See Example A-13 for a few examples of LDAP response elements.
Example: A-13 LDAP response elements
<batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
...
<modifyResponse>
<resultCode code="53" descr="unwillingToPerform"/>
<errorMessage>System Attribute may not be modified</errorMessage>
</modifyResponse>
<addResponse>
<resultCode code="0" descr="success"/>
</addResponse>
<addResponse>
<control>...</control>
<control>...</control>
<resultCode code="0" descr="success"/>
</addResponse>
...
</batchResponse>
The matchedDN and errorMessage elements are optional and default to the empty string.
The resultCode element has an optional descr attribute.
DsmlValues
The definition of DsmlValue permits the following types: UTF-8, base64Binary, and any URI. The URI type is used to indicate that the contents of the value are to be found at a location defined by the URI.
Auth
The authRequest provides a means for a client to indicate that access control for the following requests is to be interpreted as though the requests are performed by the security principal identified by the principal attribute. The value of the principal attribute is an authzId, as defined by [RFC 2829]. This can be useful if the DSMLv2 server (or an LDAP server to which the DSMLv2 server connects) is capable of supporting proxy authorization [ID-ProxyAuth].
At most one authRequest may occur within a BatchRequest and if it does occur, it must be the first request. If authRequest operations are not supported by the server to which the BatchRequest is sent, then the server must not process the following requests and must return a BatchResponse with an authResponse containing an LDAPResultCode of 'authMethodNotSupported'. If authRequest operations are supported, then if there are access rights errors, processing proceeds as for a BatchRequest without an authRequest; that is, an appropriate errorResponse is generated, etc.
See Example A-14 on page 649 for an example of an authRequest.
Example: A-14 authRequest example
<authRequest principal="dn:CN=Bob Rush,OU=Dev,DC=Example,DC=COM"/>
See Example A-15 for an example of an authResponse.
Example: A-15 authReqponse example
<authResponse>
<resultCode code="0"/>
</authResponse>
Modify
DSMLv2 specifies each attribute modification by attaching an operation attribute to an attr element. As in LDAP, an operation can be add, delete, or replace.
See Example A-16 for an example of a modifyRequest.
Example: A-16 modifyRequest example
<?xml version="1.0" encoding="UTF-8"?>
<dsml:batchRequest xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<dsml:modifyRequest dn="cn=chunhui yang,o=ibm">
<modification name="telephoneNumber" operation="add">
<value>123 456 7890</value>
<value>919 824 9855</value>
</modification>
<modification name="sn" operation="replace">
<value>Richard</value>
</modification>
</dsml:modifyRequest>
</dsml:batchRequest>
See Example A-17 for an example of a modifyResponse.
Example: A-17 modifyResponse example
<modifyResponse>
<resultCode code="53" descr="unwillingToPerform"/>
<errorMessage>System Attribute may not be modified</errorMessage>
</modifyResponse>
Search
The DSMLv2 search encoding is based on the LDAP search encoding, but with some changes as described in Section A. In the searchRequest encoding:
•baseObject. Following DSMLv1 conventions, the distinguished name of the search base is expressed as the XML attribute dn.
<searchRequest dn="OU=Marketing,DC=Example,DC=COM" />
•sizeLimit, timeLimit, typesOnly. These elements default to 0, 0, and FALSE respectively.
•attributes. In RFC 2251, attributes is a sequence of attribute names, which is translated into a sequence of elements containing attribute names.
See Example A-18 for an example of the attributes element.
Example: A-18 attributes element example
<attributes>
<attribute name="sn"/ >
<attribute name="givenName"/>
<attribute name="title"/>
</attributes>
See Example A-19 for a full SearchRequest example.
Example: A-19 searchRequest example
<?xml version="1.0" encoding="UTF-8"?>
<dsml:batchRequest xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<dsml:searchRequest
dn="o=ibm"
scope="wholeSubtree"
derefAliases="neverDerefAliases"
sizeLimit="1000">
<dsml:filter>
<dsml:and>
<dsml:substrings name="givenName">
<initial>S</initial>
</dsml:substrings>
<dsml:equalityMatch name="objectclass">
<value>inetorgperson</value>
</dsml:equalityMatch>
</dsml:and>
</dsml:filter>
<dsml:attributes>
<dsml:attribute name="cn"/>
<dsml:attribute name="sn"/>
<dsml:attribute name="l"/>
</dsml:attributes>
</dsml:searchRequest>
</dsml:batchRequest>
The response to a searchRequest is logically called a searchResponse. According to RFC 2251, a search response contains:
•Zero to many searchResultEntry
•Zero to many searchResultReference
•One searchResultDone
DSMLv2 permits wrapping all of these related elements into one searchResponse envelope.
Each searchResultEntry, searchResultReference, and searchResultDone MAY have zero or more LDAP controls, consistent with RFC 2251.
See Example A-20 for an example of a searchResultEntry (with terminating searchResultDone).
Example: A-20 searchResultntry example
<searchResponse>
<searchResultEntry dn="OU=Development,DC=Example,DC=COM">
<attr name="allowedAttributeEffective">
<value>description</value>
<value>ntSecurityDescriptor</value>
<value>wwwHomepage</value>
</attr>
</searchResultEntry>
<searchResultEntry dn="CN=David,OU=HR,DC=Example,DC=COM">
<attr name="objectclass"><value>person</value></attr>
<attr name="sn"><value>Johnson</value></attr>
<attr name="givenName"><value>David</value></attr>
<attr name="title"><value>Program Manager</value></attr>
</searchResultEntry>
<searchResultEntry dn="CN=JSmith, OU=Finance,DC=Example,DC=COM">
<attr name="objectclass"><value>top</value></attr>
<attr name="objectclass"><value>person</value></attr>
<attr name="objectclass"><value>organizationalPerson</value></attr>
<attr name="sn"><value>Smith</value></attr>
</searchResultEntry>
<searchResultDone>
<control type="1.2.840.113556.1.4.621" criticality="false">
<controlValue xsi:type="xsd:base64Binary">
U2VhcmNoIFJlcXVlc3QgRXhhbXBsZQ==
</controlValue>
</control>
<resultCode code="0"/>
</searchResultDone>
</searchResponse>
See Example A-21 for an example of a searchResultReference.
Example: A-21 searchResultReference example
<searchResponse>
<searchResultReference>
<ref>ldap://srv01.example.com/OU=Marketing,DC=Example,DC=COM</ref>
<ref>ldap://srv05.fabrikam.com/DC=Fabrikam,DC=COM</ref>
</searchResultReference>
...
</searchResponse>
Add
See Example A-22 for an example of an addRequest.
Example: A-22 addRequest example
<?xml version="1.0" encoding="UTF-8"?>
<dsml:batchRequest xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<dsml:addRequest dn="cn=chunhui yang,o=ibm">
<attr name="objectclass">
<value>top</value>
</attr>
<attr name="objectclass">
<value>person</value>
</attr>
<attr name="objectclass">
<value>organizationalPerson</value>
</attr>
<attr name="objectclass">
<value>inetorgperson</value>
</attr>
<attr name="sn">
<value>Yang</value>
</attr>
<attr name="givenName">
<value>chunhui</value>
</attr>
<attr name="title">
<value>ITDS consultant</value>
</attr>
</dsml:addRequest>
</dsml:batchRequest>
See Example A-23 for an example of an addResponse.
Example: A-23 addResponse example
<addResponse>
<resultCode code="0"/>
<errorMessage>completed</errorMessage>
</addResponse>
Delete
See Example A-24 for an example of a delRequest.
Example: A-24 delRequest example
<?xml version="1.0" encoding="UTF-8"?>
<dsml:batchRequest xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<dsml:delRequest dn="cn=deleteperson,o=ibm">
</dsml:delRequest>
</dsml:batchRequest>
See Example A-25 for an example of a delResponse.
Example: A-25 delResponse example
<delResponse matchedDN="OU=HR,DC=Example,DC=COM">
<resultCode code="32" descr="noSuchObject"/>
<errorMessage>DSDEL::230234</errorMessage>
</delResponse>
ModifyDN
See Example A-26 for an example of a modDNRequest.
Example: A-26 modDNRequest example
<modDNRequest dn="CN=Alice Johnson,DC=Example,DC=COM"
newrdn="Alice Weiss"
deleteoldrdn="true"
newSuperior="OU=Marketing,DC=Example,DC=COM"/>
See Example A-27 on page 654 for an example of a modDNResponse.
Example: A-27 modDNResponse example
<modDNResponse>
<resultCode code="0" descr="success"/>
</modDNResponse>
Compare
See Example A-28 for an example of a compareRequest.
Example: A-28 compareRequest example
<compareRequest dn="CN=Johnson,OU=HR, DC=Example,DC=COM">
<assertion name="sn"><value>Johnson</value></assertion>
</compareRequest>
See Example A-29 for an example of a compareResponse.
Example: A-29 compareResponse example
<compareResponse>
<resultCode code="6" descr="compareTrue"/>
</compareResponse>
Extended Operation
See Example A-30 for an example of an extendedRequest.
Example: A-30 extendedRequest example
<extendedRequest>
<requestName>1.3.563.52.424</requestName>
<requestValue
xsi:type="xsd:base64Binary">TFNNTHYyLjAgcm9ja3MhIQ==
</requestValue>
</extendedRequest>
See Example A-31 for an example of an extendedResponse.
Example: A-31 extendedResponse example
<extendedResponse>
<resultCode code="0"/>
<response xsi:type="xsd:base64Binary">RFNNTHYyLjAgcm9ja3MhIQ==</response>
</extendedResponse>
Bindings
DSMLv2 defines two normative bindings:
•A SOAP request/response binding
•A file binding that serves as the DSMLv2 analog of LDIF
SOAP Binding
The following describes the DSMLv2 SOAP [W3C SOAP] request/response binding.
The namespace for DSMLv2 is "urn:oasis:names:tc:DSML:2:0:core". This namespace is used at the top-level element of the <body> of each SOAP request and response. Default namespace designations may be used.
All SOAP requests and responses in this binding MUST use the xml encoding "UTF-8".
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.
Each SOAP response body contains a single batchResponse.
A SOAP Fault is used only when an error occurs outside the scope of DSMLv2 processing. For example, the SOAP Server is not able to find or connect to a DSMLv2 server to process a DSMLv2 document. If errors happen during DSMLv2 processing, then they are conveyed as a DSMLv2 response document in the SOAP response message.
See Example A-32 for an example of a SOAP request.
Example: A-32 SOAP request example
<se:Envelope xmlns:se="http://schemas.xmlsoap.org/soap/envelope/"
se:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<se:Body xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
<dsml:batchRequest>
<dsml:modifyRequest>...</dsml:modifyRequest>
<dsml:addRequest>...</dsml:addRequest>
...
</dsml:batchRequest>
</se:Body>
</se:Envelope>
See Example A-33 on page 656 for an example of a SOAP response.
Example: A-33 SOAP response example
<se:Envelope xmlns:se="http://schemas.xmlsoap.org/soap/envelope/"
se:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<se:Body xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
<dsml:batchResponse>
<dsml:modifyResponse>...</dsml:modifyResponse>
<dsml:addResponse>...</dsml:modifyResponse>
...
</dsml:batchResponse>
</se:Body>
</se:Envelope>
See for an example of a SOAP fault.
Example: A-34 SOAP Fault example
<se:Envelope xmlns:se="http://schemas.xmlsoap.org/soap/envelope/"
se:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<se:Body>
<se:Fault>
<faultcode>se:Server</faultcode>
<faultstring>Server Error</faultstring>
<detail>Cannot connect to a DSMLv2 server</detail>
</se:Fault>
</se:Body>
</se:Envelope>
This binding does not specify any SOAP headers.
A minimal implementation supports DsmlValue URIs of type file, which are evaluated by the client provider using the security context associated with the client. Individual implementations may support additional URI types. If the client provider is unable to resolve the URI to a value that can transferred to the server, then the provider must return an errorResponse with type="unresolvableURI".
Authentication in this binding is the ID and password which comes in as part of HTTP authentication, and is reused to bind to LDAP.
File binding
The file binding is an alternative to the LDAP Data Interchange Format (LDIF) described by [RFC 2849]. Its primary advantages over LDIF are:
•Use of XML, which is more natural for many clients to generate and to parse than LDIF. Also benefits from the comparative wealth of tools.
•Formalization of output on error conditions, such as in the event the directory server is unavailable or the directory server returns an LDAP error.
The top-level document for the input file is an element of type BatchRequest with name batchRequest. The top-level document for the output file is an element of type BatchResponse with name batchResponse.
A minimal implementation supports DsmlValue URIs of type file, which are evaluated by the command-line program using the security context associated with the process running the command-line program. Individual implementations MAY support additional URI types. If the client provider is unable to resolve the URI to a value that can transferred to the server, then the command-line program MUST return an errorResponse with type="unresolvableURI".
The file binding authenticates to the directory using the user identity and password with which the command-line program was invoked.
DSML communication between ITDI and ITDS
ITDI is IBM's another directory product which focuses on directory integration practice. It can acts as a DSML client or a DSML service to communicate with ITDS DSML server.
ITDS DSML Client to ITDI DSML Service
ITDS DSML client application sends DSML request to ITDI, and ITDI HTTP EH will trigger an AssemblyLine which uses HTTP client connector and SOAP parser to deconstruct the DSML request, connects to ITDS server and executes the operation defined in the DSML request, and then sends the DSML response back to ITDS DSML client application.
ITDI DSML Client to ITDS DSML Server
ITDI can uses its HTTP client connector to send DSML request, ITDS DSML server receives the DSML request, parses the DSML document, convert the DSML operation into JNDI operation, executes the requested operation in the LDAP server via JNDI, and sends DSML response back to ITDI.
ITDS DSML Service Deployment
This section covers the detailed steps of ITDS DSML service installation, configuration, and execution.
Installation
In order to install ITDS DSML Service, you will need to download the DSML.zip file, install application server (WAS), install SOAP, and then install DSML into WAS. These steps are described in the following section.
DSMLzip file
Directory Services Markup Language (DSML) is installed as a .zip file named DSML.zip in the installpath/idstools (or installpathidstools for Windows systems) directory when you install the Web Administration Tool.
|
Note: During standard IBM Directory Server installation, you must select the WebAdmin package.
|
After you unzip the DSML.zip file, the DSML.zip file can be found in your <LDAPHome>idstools directory, the following files are contained in the .zip file.
DSMLReadme.txt
Describes the files in the package and more detailed instructions on how to install and configure DSML and placement of .jar files.
dsml.pdf
Describes how to use DSML. This file is in PDF format.
dsml.htm
Describes how to use DSML, in HTML format.
|
Note: The Web Administration Tool is NOT for the faint of heart: Requires specific Java files and CLASSPATH setup, knowledge of installing apps into the Application Server, plus knowledge of SOAP and XML.
|
Install Application Server (WAS)
The Application Server is required.The embedded Websphere Application Server 5.0 Express provided with the IBM Directory Server installation is preferred. Tomcat is also supported. The following steps should be performed when installation the application server:
•Install IBM Directory 5.2 with WebAdmin package and Websphere Application Server and GSKit6.
•Configure your ITDS 5.2 Admin DN and Password, and database (in order to test WAS with the Web Admin).
•Make sure the Websphere Application Server Express starts successfully.
•Type the following commands in the installation folderappsrvin directory:
In Windows: startServer server1
In Unix: startServer.sh server1
•Test WAS by starting the WebAdmin at the following default URL:
http://<hostname>:9080/IDSWebApp/IDSjsp/Login.jsp
•If desired, go ahead and configure your new 5.2 LDAP server into WAS.
Install Java SDK 1.3.1
Java SDK 1.3.1 (not just the JRE) is needed. WebSphere Express contains an acceptable version in the ...appsrvjava directory. The preferred level of the 1.3.1 SDK is Service Release 2 or greater. This can be obtained at:
On this page, download File: XML4J-bin.4.1.2.zip. The files needed from this zip file are xercesImpl.jar, xmlParserAPIs.jar.
Install SOAP
To install:
•Apache SOAP 2.3 must be installed into the Application Server before installing our DSML. This can be obtained at:
On this page, download file soap-bin-2.3.zip. The files needed from this zip file are soap.war, soap.jar.
•Some specific Java packages must be downloaded from the Web in order to get some of the Java .jar files required by DSML. (See Table A-1 for the Java files that are needed.)
Unzip the packages and copy the .jar files to <WAS>appsrvlib.
Copy the soap.war file to <WAS>appsrvinstallableApps.
•Configure Apache SOAP 2.3 into WAS.
Set your JAVA_HOME and CLASSPATH to values discussed in the DSMLreadme.txt file.
– Download the 5 JAR files listed in Table A-1 to install the DSML Server. These files are required for the install.bat or install.sh file to work.
Table A-1 JAR files needed to install the DSML Server
|
Filename
|
Description
|
Download location
|
|
mail.jar
|
Java Mail
|
|
|
activation.jar
|
JavaBeans
|
|
|
XercesImpl.jar
|
XML4Java
|
|
|
XMLParserAPIs.jar
|
XML4Java
|
|
|
soap.jar
|
Apache SOAP
|
– Set the CLASSPATH variable to point all of the jar files you downloaded.
CLASSPATH should point to soap.jar, xercesImpl.jar, xmlParserAPIs.jar xerces.jar, activation.jar, and mail.jar.
Additional classpath setting that is not included in the dsmlreadme.txt file and WAS:
appsrvinstalledAppsDefaultNodesoap.war.earsoap.warWEB-INFclasses
Such as:
C:PROGRA~1IBMLDAPappsrvinstalledAppsDefaultNodesoap.war.earsoap.warWEB-INFclasses;
See Example A-35 for an example of classpath settings.
Example: A-35 CLASSPATH settings
.;C:PROGRA~1IBMLDAPappsrvlibjaf-1.0.2activation.jar;
C:PROGRA~1IBMLDAPappsrvlibjavamail-1.3.1mail.jar;
C:PROGRA~1IBMLDAPappsrvlibxml4j-4_2_2XercesImpl.jar;
C:PROGRA~1IBMLDAPappsrvlibxml4j-4_2_2XMLParserAPIs.jar;
C:PROGRA~1IBMLDAPappsrvinstalledAppsDefaultNodesoap.war.earsoap.warWEB-INFclasses;
– Set the JAVA_HOME variable to <WASinst>/java/.
JAVA_HOME must point to a true Java 1.3.1 SDK (not just a JRE). The <WAS>/appsrv/java directory contains an acceptable 1.3.1 JDK.
– Set the PATH variable to <WASinst>/java/bin.
– Make sure the file soap.war is in the <WAS>/appsrv/installableApps directory.
– GSKit6 (which comes with our product) contains several .jar files that are needed by DSML.
•Run the following WAS command (one long line).
The command shown in Example A-36is the Windows version, and you should replace '<WAS>' with the directory where the WAS 'appsrv' directory exists.
Example: A-36 WAS command
<WAS>appsrvinwsadmin.bat -conntype NONE -node DefaultNode
-c "$AdminApp install {<WAS>/appsrv/installableApps/soap.war}
{-configroot "<WAS>config" -node DefaultNode -usedefaultbindings
-nodeployjb -appname soap.war -context "soap"}
|
Note: Make sure all the back-slashes, double-quotes, and backslashes are correct.
|
See Example A-37 for an example of how to create a soapinstall.bat file to run the WAS command.
Example: A-37 soapinstall.bat file
wsadmin.bat -conntype NONE -c "$AdminApp install {C:Program FilesIBMLDAPappsrv/installableApps/soap.war} {-configroot "C:Program FilesIBMLDAPconfig" -node DefaultNode -usedefaultbindings -nodeployejb -appname soap.war -contextroot "soap"}"
After the installation, you will see something similar to Example A-38.
Example: A-38 soapinstall.bat output messages
C:Program FilesIBMLDAPappsrvin>soapinstall
C:Program FilesIBMLDAPappsrvin>wsadmin.bat -conntype NONE -c "$AdminApp install {C:Program FilesIBMLDAPappsrv/installableApps/soap.war} {-configroot "C:Program FilesIBMLDAPconfig" -node DefaultNode -usedefaultbindings -nodeployejb -appname soap.war -contextroot "soap"}"
WASX7357I: By request, this scripting client is not connected to any server process. Certain configuration and application operations will be available in local mode.
ADMA6016I: Add to workspace META-INF/application.xml
ADMA6017I: Saved document C:Program FilesIBMLDAPappsrvwstempScriptf95c04264eworkspacecellsDefaultNodeapplicationssoap.war.eardeploymentssoap.warMETA-INFibm-applcation-bnd.xmi
ADMA6016I: Add to workspace META-INF/ ibm-applcation-bnd.xmi
ADMA6017I: Saved document C:Program FilesIBMLDAPappsrvwstempScriptf95c04264eworkspacecellsDefaultNodeapplicationssoap.war.eardeploymentssoap.warMETA-INFMANIFEST.MF
ADMA6016I: Add to workspace META-INF/ MANIFEST.MF
ADMA6017I: Saved document C:Program FilesIBMLDAPappsrvwstempScriptf95c04264eworkspacecellsDefaultNodeapplicationssoap.war.eardeploymentssoap.warWEB-INFweb.xml
ADMA6016I: Add to workspace soap.war/WEB-INF/web.xml
ADMA6017I: Saved document C:Program FilesIBMLDAPappsrvwstempScriptf95c04264eworkspacecellsDefaultNodeapplicationssoap.war.eardeploymentssoap.warWEB-INFibm-web-bnd.xmi
ADMA6016I: Add to workspace soap.war/WEB-INF/ibm-web-bnd.xml
ADMA5005I: Application soap.war configured in WebSphere repository
ADMA5037I: Starting backup of app at C:Program FilesIBMLDAPappsrvwstempScriptf95c04264eworkspacecellsDefaultNodeapplicationssoap.war.ear
ADMA5037I: Completed backup of app at C:Program FilesIBMLDAPappsrvwstempScriptf95c04264eworkspacecellsDefaultNodeapplicationssoap.war.ear
ADMA5037I: Application binaries saved in C:Program FilesIBMLDAPappsrvwstempScriptf95c04264eworkspacecellsDefaultNodeapplicationssoap.war.ear
ADMA5037I: Deleting directory tree C:DOCUME~1ADMINI~1LOCALS~1Tempapp_f95c0454e5
ADMA5011I: Cleanup of temp dir for app soap.war done.
ADMA5031I: Application soap.war installed successfully
•Stop and restart the WAS server after a successful SOAP install.
You will see information similar to Example A-39 during the restart process.
Example: A-39 Restart WAS output
C:Program FilesIBMLDAPappsrvin>stopServer server1
ADMU0116I: Tool information is being logged in file C:Program
FilesIBMLDAPappsrvlogsserver1stopServer.log
ADMU3100I: Reading configuration for server: server1
ADMU3201I: Server stop request issued. Waiting for stop status.
ADMU4000I: Server server1 stop completed.
C:Program FilesIBMLDAPappsrvin>startServer server1
ADMU0116I: Tool information is being logged in file C:Program
FilesIBMLDAPappsrvlogsserver1startServer.log
ADMU3100I: Reading configuration for server: server1
ADMU3200I: Server launched. Waiting for initialization status.
ADMU3000I: Server server1 open for e-business; process id is 900
Install DSML into WAS
To install:
•Make sure the WAS Express server has restarted successfully.
•Test SOAP is working through WAS by opening a browser and going to the URL:
http://<yourmachinename>:9080/soap/servlet/rpcrouter
•You should see a page with a message similar to SOAP RPC Router - Sorry, we do not speak via HTTP GET ... use HTTP POST, as shown in Figure A-4.
Figure A-4 Testing SOAP through WAS
•Install DSML using the following commands from the c:dsml directory:
– On Windows platforms:
install <SOAPHomeDir> <RPCRouterURL>
– On UNIX platforms:
chmod u+x install.sh
./install.sh <SOAPHomeDir> <RPCRouterURL>
See Example A-40 for a Windows example.
Example: A-40 Installing DSML on Windows
install <WAS>appsrvinstalledAppsDefaultNodesoap.war.earsoap.war http://<yourmachinename>:9080/soap/servlet/rpcrouter
|
Note: If there is a space (such as C:Program Files...) in your JAVA_HOME, you should quote "%JAVA_HOME%" in the install.bat file.
|
You should see some files copied with a message at the end that says if there were no error messages the install was successful, as shown in Example A-41. There should not be any Java exceptions.
Example: A-41 DSML install output
C:Program FilesIBMLDAPidstoolsDSML>install C:Progra~1IBMLDAPappsrvinstalledAppsDefaultNodesoap.war.earsoap.war http://lcoalhost:9080/soap/servlet/rptrouter
1 file(s) copied.
.jarsauibase.jar
.jarsdsml.jar
.jarsIBMLDAPJavaBer.jar
.jars
egex4j.jar
4 file(s) copied.
.jarsauibase.jar
.jarsdsml.jar
.jarsIBMLDAPJavaBer.jar
.jars
egex4j.jar
4 file(s) copied.
1 file(s) copied.
1 file(s) copied.
Verified existence of logs directory: C:Progra~1IBMLDAPappsrvinstalledAppsDefaultNodesoap.war.earsoap.warlogs.
Verified existence of WEB-INF/lib directory: C:Progra~1IBMLDAPappsrvinstalledAppsDefaultNodesoap.war.earsoap.warWEB-INFlib.
Deploying the eCopy service....
Verify that its there
Deployed Services:
Urn:oasis:.namesLtcLDSML:2:0:core
If you have not received any errors during the install, installation is now complete. Please restart your application server.
C:Program FilesIBMLDAPidstoolsDSML>
If you see the Java exception as shown in Example A-42, it means that your localhost is not found.
Example: A-42 Java exception for localhost not found
Exception in thread "main" [SOAPException: faultCode=SOAP-ENV:Client; msg=Error opening socket: java.net.UnknownHostException: localhost;targetException=java.lang.IllegalArgumentException: Error opening socket: java.net.UnknownHostException: lcoalhost]
at org.apache.soap.transport.http.SOAPHTTPConnection.send(Unknown Source)
at org.apache.soap.rpc.Call.invoke(Unknown Source)
at org.apache.soap.server.ServiceManagerClient.invokeMethod(Unknown Source)
at org.apache.soap.server.ServiceManagerClient.deploy(Unknown Source)
at org.apache.soap.server.ServiceManagerClient.main(Unknown Source)
If you see the Java exception as shown in Example A-43, it means that your class path for those required jar files are not set correctly.
Example: A-43 Java exception for CLASSPATH not being set correctly
[Error] Thu Dec 11 19:56:38 EST 2003 <== DsmlSoapClient.main(String[]) (Exception)
java.io.FileNotFoundException:
C:Program FilesIBMLDAPidstoolsDSMLDsmlRequest.xml
(The system cannot find the file specified)
at java.io.FileInputStream.open(Native Method)
at java.io.FileInputStream.<init>(FileInputStream.java:103)
at java.io.FileInputStream.<init>(FileInputStream.java:66)
at sun.net.www.protocol.file.FileURLConnection.connect
(FileURLConnection.java:69)
at sun.net.www.protocol.file.FileURLConnection.getInputStream
(FileURLConnection.java:156)
at java.net.URL.openStream(URL.java:960)
at org.apache.xerces.impl.XMLEntityManager.setupCurrentEntity
(Unknown Source)
at org.apache.xerces.impl.XMLVersionDetector.determineDocVersion
(Unknown Source)
at org.apache.xerces.parsers.XML11Configuration.parse(Unknown Source)
at org.apache.xerces.parsers.DTDConfiguration.parse(Unknown Source)
at org.apache.xerces.parsers.XMLParser.parse(Unknown Source)
at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)
at org.apache.xerces.jaxp.DocumentBuilderImpl.parse(Unknown Source)
at javax.xml.parsers.DocumentBuilder.parse(DocumentBuilder.java:124)
at com.ibm.ldap.dsmlClient.DsmlSoapClient.main(DsmlSoapClient.java:205)
•When DSML is successfully installed, you will receive the messages "Deploying Service" and "Verifying". You are then prompted to restart your application server.
SSL with DSML
The following documentation should be reviewed to help set up SSL with DSML.
•DSMLReadme.txt file (located inside the DSML.zip file)
•IBM Directory Server 5.1 Administration Guide - Chapter 7
•IBM Directory Server 5.1 Installation and Configuration Guide - Appendix G
•GSKit documentation
Some of the main tasks associated with setting up SSL are:
•Creating the key database/trust store database with the ikeyman utility on the Directory Server machine.
•Creating a self-signed certificate for LDAP server (or acquiring a real certificate).
•Exporting the LDAP server's SSL certificate into the key database.
•Importing the LDAP certificate to WAS for 1-way handshaking.
•Creating a self-signed certificate for SOAP server if 2-way SSL handshaking is desired.
•Updating the <JAVA_HOME>jrelibsecurityjava.security file with proper provider information.
•Updating SOAP's DSMLSSLConfig.xml file to recognize the certificate.
Configuration
DSML Service configuration settings include the logging and SSL settings on the server.
Logging
The DSML server will log to the file defined by the LogFile parameter in the trace.properties file, the default LogFile name is DSMLLLog.txt. What gets logged is defined by four configurable options that are also set in the trace.properties file contained in <SOAPHomeDir>WEB-INF.
The four options and descriptions that can be set in the trace.properties file are:
•trace.information: Possible values are true and false. When set to false, log messages that are informational in nature will be suppressed. Otherwise, they will be written to the log file.
•trace.diagnostic: Possible values are true and false. When set to false, log messages that are diagnostic (tracing) in nature will be suppressed. Otherwise, they will be written to the log file.
•trace.warning: Possible values are true and false. When set to false, warning messages will be suppressed. Otherwise, they will be written to the log file.
•trace.error: Possible values are true and false. When set to false, error messages will be suppressed. Otherwise, they will be written to the log file.
|
Note: As more tracing options are turned on, performance will drop.
|
See Example A-44 on page 666 for an example of the trace.properties file.
Example: A-44 Logging options in the trace.properties file
trace.information=false
trace.diagnostic=false
trace.warning=true
trace.error=true
SSL
Modify the java.security file in your %JAVA_HOME%jrelibsecurity directory as follows:
•After the line "security.provider.1=sun.security.provider.Sun" place the following 2 lines (if you have other providers installed, the numbers may be different):
security.provider.2=com.ibm.crypto.provider.IBMJCE
security.provider.3=com.ibm.crypto.provider.IBMJCA
•The following options must be set in the DSMLSSLConfig.xml file located in <SOAPHome>WEB-INFclassessecurity directory for SSL to be used.
– SSL: Toggles the use of SSL. Once SSL is turned "on," all bindings between the DSML server and an LDAP server will be made using SSL. If the DSML server attempts to bind to a non-secure port on an LDAP server with SSL turned on, it will fail.
– dsmlKeyRingFile: Specifies the fully qualified pathname to the Keyring file to be used in secure connections.
– dsmlKeyRingPassword: Password for Keyring File.
– dsmlKeyRingFiletype: Keyring file type.
– dsmlTrustStoreFile: Specifies the fully qualified pathname to the trust store file to be used in secure connections.
– dsmlTrustStorePassword: Password for trust store file.
– dsmlTrustStoreFiletype: Trust store file type.
|
Note: The DSMLSSLConfigFileSchema.xsd file must be in the %JAVA_HOME%/jre directory. (This is done by default during installation.)
|
See Example A-45 for an example of the DSMLSSLConfig.xml file.
Example: A-45 DSMLSSLConfig.xml file
<?xml version="1.0" encoding="UTF-8" ?>
<DsmlSSLConfigxmlns="sslConfig"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SSL>off</SSL>
<dsmlKeyRingFile>d:keyrings
amtp2.jks</dsmlKeyRingFile>
<dsmlKeyRingPassword>secret</dsmlKeyRingPassword>
<dsmlKeyRingFiletype>jks</dsmlKeyRingFiletype>
<dsmlTrustStoreFile>d:keyrings
amtp2.jks</dsmlTrustStoreFile>
<dsmlTrustStorePassword>secret</dsmlTrustStorePassword>
<dsmlTrustStoreFiletype>jks</dsmlTrustStoreFiletype>
</DsmlSSLConfig>
|
Note: Most of the configuration of the clients is performed via command line at runtime. The only option configurable before runtime is the classpath, the requirements for which are listed above in the INSTALLATION section.
|
Execution
In this section we will discover how to execute IBM DSML service.
Server
Execution of the server is broken up into the SOAP binding component and the file binding component. The DMSL request is transformed into a JNDI call and it does all of the request for you to the LDAP server via JNDI.
SOAP binding
After DSML server has been deployed within SOAP, requests are made against it by submitting them to the SOAP webapp's messagerouter servlet. For Tomcat users, this URL should be similar to http://host:port/soap/servlet/messagerouter. Simply submit a SOAP request to this URL, and you should receive a corresponding SOAP response. For the DSML SOAP component to function, the message files must be present in SOAPHomeDirmsg.
File binding
Execution of the server via file binding is achieved by invoking the DsmlFileClient with an XML input file containing a batchRequest element. To execute the DsmlFileClient, the message files must be present in a directory listed in the CLASSPATH.
|
Note: The DSMLSSLConfigFileSchema.xsd file must be in the %JAVA_HOME%/jre directory. (This is done by default during installation.)
|
Clients
There are two types of DSML Clients applications in IBM DSML Service: DsmlSoapClient and DsmlFileClient.
DsmlSoapClient
Description: Used to submit a DSML request via SOAP to a DSML server deployed within a SOAP webapp.
Syntax:
java com.ibm.ldap.dsmlClient.DsmlSoapClient LDAP-userid LDAP-password [OPTIONS]
Options:
•-d debug - specified level of tracing (logically OR'ed bit flags - add numbers of desired debug levels)
– ERROR = 1
– WARNING = 2
– DIAGNOSTIC = 4
– INFORMATION = 8
•-i inputFileName - File containing DSMLrequest
•-l logFileName - Log file name (full path)
•-o outputFileName - File to contain DSML response
•-S DSMLSOAPserver - URL to SOAP messagerouter
•-s LDAP Server URL - LDAP server to which the DSML request applies
Defaults:
•debug = 3 (WARNING + ERROR)
•LDAP Server URL = DSML server default
•logFileName = DsmlLog.txt in the current directory
•inputFileName = DsmlRequest.xml in the current directory
•outputFileName = DsmlResponse.xml in the current directory
LDAP user ID and password, as well as SOAP user ID and password must be supplied.
DsmlFileClient
Description: Used to submit a file bound DSML request via a DSML server residing on the same computer as DsmlFileClient.
Syntax:
java com.ibm.ldap.dsmlClient.DsmlFileClient LDAP-userid LDAP-password [OPTIONS]
Options:
•-d debug - specified level of tracing (logically OR'ed bit flags - add numbers of desired debug levels)
– ERROR = 1
– WARNING = 2
– DIAGNOSTIC = 4
– INFORMATION = 8
•-i inputFileName - File containing DSML request
•-l logFileName - Log file name (full path)
•-o outputFileName - File to contain DSML response
•-s LDAP Server URL - LDAP server to which the DSML request applies
Defaults:
•debug = WARNING + ERROR (3)
•inputFileName = DsmlRequest.xml in the current directory
•logFileName = DsmlLog.txt in the current directory
•outputFileName = DsmlResponse.xml in the current directory
•ldapServer = ldap://localhost:389/
LDAP user ID and password must be supplied.
See Example A-46 for an example of using DsmlFileClient to submit a DSML search request.
Example: A-46 Using DsmlFileClient to submit a DSML search request
java com.ibm.ldap.dsmlClient.DsmlFileClient LDAP-userid LDAP-password
The DSML request file can be AddRequest, DelRequest, ModifyRequest, SearchRequest.
Note that if you want the DsmlFileClient to connect to the LDAP server using SSL, the DSMLSSLConfig.xml file must be in a directory that is in your CLASSPATH. See the SSL section of this document for information about the format of the DSMLSSLConfig.xml file.
Note that you need to copy DSMLSSLConfigFileSchema.xsd from the dsml unzipped folder to C:Program FilesJavaj2re1.4.1_05.
There are extra classpath settings needed to run the DsmlFileClient. The classpath needs the following dsml jar files: dsml.jar, etc. as the following C:DSMLjarsauibase.jar;C:DSMLjarsdsml.jar;C:DSMLjars
egex4j.jar;C:DSMLjarsIBMLDAPJavaBer.jar;C:DSML; and be sure to set the servlet.jar classpath: C:DSMLservlet.jar.
See Example A-47 on how to set a classpath.
Example: A-47 Setting the CLASSPATH
Set classpath=.;C:DSMLjarsauibase.jar;C:DSMLjarsdsml.jar;
C:DSMLjars
egex4j.jar;
C:DSMLjarsIBMLDAPJavaBer.jar;
C:DSML;
C:Progra~1IBMLDAPappsrvlibj2ee.jar;
C:PROGRA~1IBMLDAPappsrvlibjaf-1.0.2activation.jar;
C:PROGRA~1IBMLDAPappsrvlibjavamail-1.3.1mail.jar;
C:PROGRA~1IBMLDAPappsrvlibxml4j-4_2_2XercesImpl.jar;
C:PROGRA~1IBMLDAPappsrvlibxml4j-4_2_2XMLParserAPIs.jar;
C:Progra~1IBMLDAPappsrvlibsoap.jar;
C:PROGRA~1IBMSQLLIBjavadb2java.zip;
C:PROGRA~1IBMSQLLIBjavadb2jcc.jar;
C:PROGRA~1IBMSQLLIBjavadb2jcc_license_cu.jar;
C:PROGRA~1IBMSQLLIBin;
C:PROGRA~1IBMSQLLIBjavacommon.jar;
You should be able to see the result of running the rundsmlfileclient command as being similar to Example A-48.
Example: A-48 Output from the rundsmlfileclient command
C:Program FilesIBMLDAPidstoolsDSML>rundsmlfileclient
C:Program FilesIBMLDAPidstoolsDSML>java com.ibm.ldap.dsmlClient.DsmlFileClient cn=root manager
[Info] CSA Toolkit Version 1 Release 3
(c) Copyright IBM Corporation 2001, 2003. All rights reserved.
Using:
Input file name: DsmlRequest.xml
Output file name: DsmlResponse.xml
LDAP server: ldap://localhost:389/
Finished processing DSML BatchRequests.
Results are in file: DsmlResponse.xml
DSMLRequest.xml
See Example A-49 for an example of a DSMLRequest.xml that can be used for DSML client to issue the request.
Example: A-49 DSMLRequest.xml for DSML client to issue a request
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
<dsml:batchRequest>
<dsml:addRequest dn="cn=chunhui Yang, o=ibm.c=us">
<dsml:attr name="objectclass">
<dsml:value>person</dsml:value>
</dsml:attr>
<dsml:attr name="objectclass">
<dsml:value>top</dsml:value>
</dsml:attr>
<dsml:attr name="cn">
<dsml:value>chunhui yang</dsml:value>
</dsml:attr>
<dsml:attr name="sn">
<dsml:value>yang</dsml:value>
</dsml:attr>
</dsml:addRequest>
</dsml:batchRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Troubleshooting
This section covers some common errors and causes that you may encounter during IBM DSML v2 implementation.
•Error: Exception in thread "main" java.lang.NoClassDefFoundError: org/w3c/dom/Node
Cause: XMLParserAPIs.jar missing from CLASSPATH or JAVA_HOME/jre/lib/ext
•Error: Exception in thread "main" java.lang.NoClassDefFoundError: com/ibm/jsse/IBMJSSEProvider
Cause: ibmjsse.jar missing from CLASSPATH or JAVA_HOME/jre/lib/ext
•Error: Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/soap/util/xml/XMLParserUtils
Cause: soap.jar missing from CLASSPATH or JAVA_HOME/jre/lib/ext
•Error: Exception in thread "main" javax.xml.transform.TransformerFactoryConfigurationError: Provider org.apache.xalan.processor.TransformerFactoryImpl not found
Cause: xalan.jar missing from CLASSPATH or JAVA_HOME/jre/lib/ext
•Error of DSMLv2.xsd:
The Error message will be like the one shown in Example A-50.
Example: A-50 DSMLv2.xsd error message
[Error] Fri Dec 12 21:23:30 EST 2003 Error at File: file:///C:/Program%20Files/IBM/LDAP/idstools/DSML/DsmlRequest.xml
[Error] Fri Dec 12 21:23:30 EST 2003 Line: 1
[Error] Fri Dec 12 21:23:30 EST 2003 Column: 79
[Error] Fri Dec 12 21:23:30 EST 2003 cvc-elt.1: Cannot find the declaration of element 'SOAP-ENV:Envelope'.
[Error] Fri Dec 12 21:23:30 EST 2003 org.xml.sax.SAXParseException: cvc-elt.1: Cannot find the declaration of element 'SOAP-ENV:Envelope'.
at org.apache.xerces.util.ErrorHandlerWrapper.createSAXParseException(Unknown Source)
at org.apache.xerces.util.ErrorHandlerWrapper.error(Unknown Source)
at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
at org.apache.xerces.impl.xs.XMLSchemaValidator.handleStartElement(Unknown Source)
at org.apache.xerces.impl.xs.XMLSchemaValidator.startElement(Unknown Source)
at org.apache.xerces.impl.XMLNSDocumentScannerImpl.scanStartElement(Unknown Source)
at org.apache.xerces.impl.XMLNSDocumentScannerImpl$NSContentDispatcher.scanRootElementHook(Unknown Source)
at org.apache.xerces.impl.XMLDocumentFragmentScannerImpl$FragmentContentDispatcher.dispatch(Unknown Source)
at org.apache.xerces.impl.XMLDocumentFragmentScannerImpl.scanDocument(Unknown Source)
at org.apache.xerces.parsers.XML11Configuration.parse(Unknown Source)
at org.apache.xerces.parsers.DTDConfiguration.parse(Unknown Source)
at org.apache.xerces.parsers.XMLParser.parse(Unknown Source)
at org.apache.xerces.parsers.DOMParser.parse(Unknown Source)
at org.apache.xerces.jaxp.DocumentBuilderImpl.parse(Unknown Source)
at javax.xml.parsers.DocumentBuilder.parse(DocumentBuilder.java:124)
at com.ibm.ldap.dsmlClient.DsmlSoapClient.main(DsmlSoapClient.java:205)
Causes: This is because in the xsd document, it should use single quote (') instead of double quote (") as shown in Example A-51.
Example: A-51 xsd document quote problem
……
<xsd:pattern value='[0-2].[0-9]+(.[0-9]+)*'/>
</xsd:restriction>
……
•Known issues:
The DSML file client throws a java exception similar to Example A-52 on page 673 when it is set up to communicate using SSL and the user tries to connect to an LDAP server that does not use SSL.
Example: A-52 SSL Java exception
SSL IS ON javax.naming.CommunicationException: 9.182.21.228:389. Root exception is javax. net.ssl.SSLProtocolException: end of file
at com.ibm.jsse.bd.a(Unknown Source)
at com.ibm.jsse.b.a(Unknown Source)
at com.ibm.jsse.b.write(Unknown Source)
at com.sun.jndi.ldap.Connection.<init>(Connection.java:226)
at com.sun.jndi.ldap.LdapClient.<init>(LdapClient.java:127)
at com.sun.jndi.ldap.LdapCtx.connect(LdapCtx.java:2398)
at com.sun.jndi.ldap.LdapCtx.<init>(LdapCtx.java:258)
at com.sun.jndi.ldap.LdapCtxFactory.getInitialContext(LdapCtxFactory.java:91)
at javax.naming.spi.NamingManager.getInitialContext(NamingManager.java:674)
at javax.naming.InitialContext.getDefaultInitCtx(InitialContext.java:255)
at javax.naming.InitialContext.init(InitialContext.java:231)
at javax.naming.InitialContext.<init>(InitialContext.java:207)
at javax.naming.directory.InitialDirContext.<init>(InitialDirContext.java:92)
at com.ibm.ldap.dsml.DsmlRequest.processRequests(DsmlRequest.java:767)
at com.ibm.ldap.dsml.DsmlServer.processDsmlRequest(DsmlServer.java:253)
at com.ibm.ldap.dsml.DsmlServer.processDsmlRequest(DsmlServer.java:402)
at com.ibm.ldap.dsml.DsmlServer.processDsmlRequest(DsmlServer.java:373)
at com.ibm.ldap.dsml.DsmlServer.processDsmlRequest(DsmlServer.java:296)
at com.ibm.ldap.dsmlClient.DsmlFileClient.main(DsmlFileClient.java:203)
The exception is not fatal and the output XML file is generated.
Java programming examples on DSML
DSML v2 integrates XML and directories by providing the ability to perform nearly all LDAP operations in XML. DSML v2 operations are purely based on LDAP counterparts, so LDAP information and operations can be directly mapped to DSML v2 operations.
As we explained earlier, on the server side, each DMSL request is transformed into a JNDI call and it does all of the request for you to the LDAP server via JNDI; on the client side, an xml application submits DSML requests cross HTTP network. In this section, we provide some sample programming codes to show you how to manipulate DSML request in Java. 4.2.1–4.2.3 are some sample java programming codes for DSML client, 4.2.4–4.2.6 are some sample java programming codes to parse dsml document, execute dsml query both in LDAP and SOAP, and retrieve result back on the server.
JNDI introduction
JNDI provides a standard interface to various directory and name services through the extensible provider architecture, it offers powerful ability to perform all the important LDAP operations from Java. The benefit of using DSML and JNDI to access a server that is providing DSML information via HTTP is that you don't need to expose information natively with LDAP in a server, especially in an enterprise environment, it is almost impossible to expose its directory information.
JNDI functionality is under javax.naming hierarchy, javax.naming classes are used to handle simple name services, and javax.naming.directory classes are extended and used to handle complex directory service.
The common two JNDI drivers for LDAP are:
•Sun LDAP provider for JNDI: com.sun.jndi.ldap.LdapCtx.Factory, it is part of main J2SE distribution.
•IBM LDAP provider for JNDI: com.sun.jndi.ldap.LdapCtx.Factory, it is part of IBM directory server client development kit.
All JNDI operations are performed by DirContext object which connects to LDAP server and then proceeds the JNDI operations. The connection has to be closed, and a NamingException will be thrown for you to handle.
Program examples
This section covers some of the basic Java programming on DSML manipulation with the latest DSML v2 operation capabilities. It covers from creation of a connection, creation of DSML document on the fly, sending DSML request and retrieving DSML response on the client side, to parsing of DSML document, converting DSML request to JNDI LDAP request, and retrieving JNDI LDAP operation result back on the server side.
DSML Client - Create the connection
Example A-53 shows you how to create the URL connection of the DSML server.
Example: A-53 DSML Client - Create the connection
……
url = new URL(DsmlURL);
connection = url.openConnection();
connection.setRequestProperty ("Authorization", "Basic " + encoding);
httpConn = (HttpURLConnection) connection;
……
DSML Client - Set the HTTP parameters
Example A-54 shows you how to set the HTTP parameters for the dsml request.
Example: A-54 DSML Client - Set the HTTP parameters
……
httpConn.setRequestProperty( "Content-Length",
String.valueOf( b.length ) );
httpConn.setRequestProperty("Content-Type","text/xml; charset=utf-8");
httpConn.setRequestProperty("SOAPAction",SOAPAction);
httpConn.setRequestMethod( "POST" );
httpConn.setDoOutput(true);
httpConn.setDoInput(true);
……..
DSML Client - Generate DSML document
If you need to generate DSML request document on the fly, you can use either Document Object Model (DOM) or Simple APIs for XML (SAX) which are interfaces to dynamically access and update document content.
See Example A-55 for an example of generating DSML document.
Example: A-55 DSML Client - Generate DSML document
……
//build new DOM document
DoucmentBuilder builder=factory.newDocumentBuilder();
dsmlDoc=builder.newDocument();
……
//create dsml batchRequest element
Element br=(Element) dsmlDoc.createElement("dsml:batchRequest");
br.setAttribute("xml:dsml", "urn:oasis:names:tc:DSML:2:0:core");
//create add request which is the child element of batchRequest element
Element ar=(Element) dsmlDoc.createElement("dsml:addRequest");
ar.setAttribute("dn", dn);
ar.appendChild(dsmlDoc.createTextNode("
");
br.appendChild(ar);
……
//create other dsml elements
……
ITDS DSML service does not require you to code anything to generate DSML document, all you need to do is to create a dsml document in a editor, and specify the dsml file name in the DSML client application commands.
DSML Client - Get DSML servlet response
Example A-56 shows you how to read the response returned from the DSML servlet.
Example: A-56 DSML Client - Get DSML servlet response
……
InputStreamReader ireader =
new InputStreamReader(httpConn.getInputStream());
…….
DSML Servlet - Parse DSML document
The steps to Parse a DSML document is shown in Example A-57 (using SAX).
Example: A-57 DSML Servlet - Parse DSML document
//create a new instance
SAXParserFactory myIns=SAXParserFactory.newInstance();
myIns.setNameSpaceAware(true);
// This is because SAX complains an expression error about the
// http://www.w3.org/2001/XMLSchema.xsd.
myIns.setValidating(false);
//create new SAX Parser
myParser=myIns.newSAXParser();
//Parse dsml file
SchemaXMLHandler myHandler = new SchemaXMLHandler();
MyParser.parse(dsmlfile, myHandler);
For detail method specification, please refer to:
DSML Servlet - JNDI DSML search
In order to perform DSML Search operation in JNDI, you have to set the DSML provider context factory, LDAP URL information that DSML Search operation is querying, LDAP credentials (userid and password), and then retrieve search return entries in DSML format. Example A-58 shows the java programming code to do this.
Example: A-58 DSML Servlet - JNDI DSML search
……
// set DSML provider context factory
Hashtable DsmlEnv=new Hashtable();
DsmlEnv.put(Context.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.dsml.DsmlCtxFactory");
// set LDAP URL and query base
DsmlEnv.put(Context.PROVIDER.URL, "ldap://localhost" + base + "?"
+ attrs + "?" + scope +"?" +filter);
// set LDAP credentials
DsmlEnv.put(Context.SECURITY_PRINCIPAL, "cn=root");
DsmlEnv.put(Context.SECURITY_CREDENTIAL, "password");
//create DirContext object to retrieve query results
DirContext DsmlCtx=new InitialDirContext(DsmlEnv)
String DsmlResult=DsmlCtx.lookup("").toString();
DsmlCtx.close();
……
The DSML search result will be in dsml:directory-entries element as shown in Example A-59, which contains multiple dsml:entry elements if there are multiple entries returned in the query result.
Example: A-59 DSML search result in dsml:directory-entries
<dsml:directory-entries>
<dsml:entry dn="entry1">
<dsml:objectclass>
<dsml:oc-value>person</dsml:oc-value>
<dsml:oc-value>top</dsml:oc-value>
</dsml:objectclass>
<dsml:attr name="cn">
<dsml:value>entry1</dsml:value>
</dsml:attr>
......
</dsml:entry>
<dsml:entry dn="entry2">
<dsml:objectclass>
<dsml:oc-value>person</dsml:oc-value>
<dsml:oc-value>top</dsml:oc-value>
</dsml:objectclass>
<dsml:attr name="cn">
<dsml:value>entry2</dsml:value>
</dsml:attr>
......
</dsml:entry>
......
</dsml:directory-entries>
DAML Servlet - JNDI create DSML SOAP request
To use JNDI to create a DSML SOAP request is pretty much the same with the previous JNDI DSML Search operation, the only difference is the context factory. See Example A-60 for an example of using JNDI to create a DSML SOAP Request. By defining the JNDI DSML SOAP context factory, any further JNDI requests on the dirContext object would be performed in DSML instead of LDAP.
Example: A-60 DAML servlet - JNDI create DSML SOAP request
……
// set DSML provider context factory
Hashtable DsmlEnv=new Hashtable();
DsmlEnv.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.dsmlv2.soap.DsmlSoapCtxFactory");
// set LDAP URL and query base
DsmlEnv.put(Context.PROVIDER.URL, "ldap://localhost:8080");
//retrieve query results
DirContext dirContext=new InitialDirContext(DsmlEnv);
String DsmlResult=DsmlCtx.lookup("").toString();
DsmlCtx.close();
DSML Servlet - JNDI operations
Like the JNDI Search operation we explained above, other JNDI operations such as modify, add can be performed in the similar way using corresponding methods of DirContext object. For more information on DirContext object methods and Context object methods, please refer to Sun's Web site located at:
References to the DSML official specifications
•ITDS 5.2 documentation
•Using LDAP for Directory Integration, SG-6163
•Implementation and Practical Use of LDAP on the IBM eServer iSeries Server, SG24-6193
•DOM documentation
•JNDI documentation
•SAX
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.