Deploying and Configuring the DSML Gateway

The Directory Services Markup Language (DSML) is a SOAP-based mechanism that can communicate with directory servers using an XML-based representation instead of the LDAP protocol. Oracle Unified Directory 11g Release 1 (11.1.1) supports the use of DSML through a web application that acts as a DSML-to-LDAP gateway, in which clients communicate with the gateway using DSML, but the gateway communicates with the directory server through LDAP.

Deploying the DSML Gateway

The DSML gateway can be deployed like any other web application, in most common application containers. The following section describes how to deploy the DSML gateway in Oracle WebLogic Server 10.3.5, on a UNIX system.

Deploying the DSML Gateway in Oracle WebLogic Server

This section assumes that you have Oracle WebLogic Server installed. If you do not, install Oracle WebLogic Server, as described in Installing Oracle WebLogic Server in Oracle Fusion Middleware Installation Guide for Oracle Unified Directory.

Configuring WebLogic Server for the DSML Gateway

Run the configuration wizard from the following location:

$ /OUD Base Location Home/oracle_common/common/bin/config.sh

On the Welcome screen, select Create a new WebLogic domain and click Next.
On the Select Domain Source screen, accept the default selection (Basic WebLogic Server Domain) and click Next.
On the Specify Domain Name and Location screen, type a domain name and specify its location.

A new WebLogic domain is created in this location. The DSML gateway will be deployed into this domain.
On the Configure Administrator User Name and Password screen, type a name and password for the user who will administer this domain.

The password must be at least eight characters and must contain at least one number or special character. Confirm the password and click Next.

Make a note of these details as you will need them to start or restart the WebLogic domain.
On the Configure Server Start Mode screen, select Production Mode.

Select a valid JDK (at least Java 1.6) and click Next.
On the Optional Configuration screen, click Next.
On the Configuration Summary screen, verify the domain details and click Create.
On the Creating Domain Screen, click Done.
Set the Java options for the WebLogic Server.
```
$ export JAVA_OPTIONS=-Djavax.xml.soap.MessageFactory=weblogic.xml.saaj.MessageFactoryImpl
```
If you do not set the Java options, an error will be returned.
Set the enforce-valid-basic-auth-credentials flag in the configuration file of the WebLogic domain (domain-home/config/config.xml, where domain-home is the domain that you created in Step 4).

For example, edit the file OUD-Base-Location-Home/user_projects/domains/base_domain/config/config.xml by adding the following line to the security-configuration element:

<enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>

For more information, see http://download.oracle.com/docs/cd/E12840_01/wls/docs103/security/thin_client.html#understanding_basic_atn.
Start the WebLogic Server by running domain-home/bin/startWebLogic.sh (where domain-home is the domain that you created in Step 4.

For example:
```
$ OUD-Base-Location-Home/user_projects/domains/base_domain/bin/startWebLogic.sh
```
Deploy the DSML Gateway WAR file, as described in the following section.

Deploying the DSML Gateway WAR File

Create a DSML directory in the addons directory and change to that directory.
```
$ cd OUD-Base-Location-Home/ORACLE_HOME/addons
$ mkdir DSML
$ cd DSML
```
Explode the DSML gateway WAR file.
```
$ jar xvf ../DSML.war
```
Edit the DSML configuration, if required.

The WEB-INF/web.xml file includes initialization parameters that can be used to specify the address (in the ldap.host parameter) and port number (in the ldap.port parameter) of the directory server to which DSML requests should be forwarded.

By default, the DSML gateway is configured to communicate with a directory server on the same system, that is, localhost) on port 389. If you need to change the host address and port number, edit the web.xml file and restart the web container.
In a browser window, connect to the WebLogic Administration Console (for example http://hostname:7001/console), where hostname is the host on which WebLogic Server is running.

Use the administrator user name and password that you established in Step 5 of the previous procedure.
Follow the WebLogic Server Documentation to install a web application (http://download.oracle.com/docs/cd/E12840_01/wls/docs103/ConsoleHelp/taskhelp/web_applications/InstallWebApplications.html).
- In step 4 of the procedure, provide the path to the exploded application (OUD-Base-Location-Home/ORACLE_HOME/addons/DSML).
- In step 6 of the procedure, select Install this deployment as an application.
- Accept the default values for the other steps.
On the left panel of the Administration Console, click Deployments.
Select the checkbox next to the DSML application and click Start then Servicing all requests.
On the Start Deployments panel, click Yes.
The DSML application is now deployed and available for use.

Confirming the DSML Gateway Deployment

After the DSML gateway has been deployed and configured, you can communicate with it by using any DSMLv2 client. The following sections describe two ways to accomplish this:

To Confirm the DSML Gateway Deployment with JXplorer
Confirming the DSML Gateway Deployment with the Directory Server Resource Kit

To Confirm the DSML Gateway Deployment with JXplorer

The JXplorer tool is a Java-based LDAP browser that can be used to browse, search, and edit the contents of an Oracle Unified Directory instance. This tool can communicate using both LDAP and DSML. Although JXplorer's DSML support does not allow authentication (and therefore is restricted to the set of operations available to anonymous users), it is still possible to use it to verify that the DSML gateway is functioning as expected.

Start JXplorer and chose the Connect option from the File menu.
The Open LDAP/DSML Connection window opens with fields for connection information. The following figure shows typical entries.
Enter the address and port number of the Web application on which the DSML gateway is running.
Choose DSMLv2 from the Protocol list.
Specify the path to the DSMLServlet in the DSML Service field.
Provide an appropriate base DN value for your directory.
Click the OK button to connect the directory server and display a JXplorer window where you can search and browse the tree (with the limitations imposed for anonymous users).

Confirming the DSML Gateway Deployment with the Directory Server Resource Kit

The Directory Server Resource Kit (DSRK) is a collection of utilities that may be used in conjunction with directory servers. It is originally intended for use with Oracle Directory Server Enterprise Editionr, but in most cases the applications also work with Oracle Unified Directory. The most recent version of the DSRK is included as part of DSEE 6.0, and it contains dsmlsearch and dsmlmodify tools that can interact with a directory server using DSML rather than LDAP.

Note that even though an older version of these DSML tools was provided with earlier versions of the Directory Server Resource Kit, the version provided with DSEE 6 is strongly recommended because it is easier to use.

Using the `dsmlsearch` Command

The dsmlsearch command is a DSML-based counterpart to the ldapsearch command. dsmlsearch operates in a similar manner to ldapsearch but there are certain key differences. To see usage information, invoke the command with no arguments, as in the following example:

$ ./dsmlsearch
usage: dsmlsearch -h http://host:port -b basedn [options] filter [attributes...]
where:
-h hostURL URL of the directory server
-b basedn  base dn for search
-D binddn  bind dn
-w passwd  bind password (for simple HTTP authentication)
use "-w - " to prompt for a password
-j pwfile  file where password is stored
-s scope   specify the scope of the search
baseObject - For searching only the base entry
singleLevel - For searching only the children
wholeSubtree - For searching the base entry and all childrens
-a deref   specify how aliases are deferenced
neverDerefAliases - Aliases are never dereferenced
derefFindingBaseObj - Dereferenced when finding the base DN
derefAlways - Dereferenced when finding below the base DN
-l seconds specify the maximum number of seconds to wait for the search
-z number  specify the maximum number of entries to return for the search
-f file    specify the name of the file containing the search filter

The dsmlsearch command differs in usage from ldapsearch:

The -h argument is used to provide a URL to use to access the server. It should include the host and port number, as well as the URI for the gateway servlet (for example, http://127.0.0.1:8080/dsml/DSMLServlet).
The -b argument is used to specify the search scope, but note that the values you provide are different (baseObjectinstead of base, singleLevelinstead of one, and wholeSubtreeinstead of sub).
The results are output in DSML format, which is not as user-friendly or human-readable as the LDIF output provided by ldapsearch.

An example usage of this tool is as follows. Note that the DSML output does not contain any line breaks, but line breaks are added here for readability.

$ ./dsmlsearch -h http://127.0.0.1:8080/dsml/DSMLServlet \ -b "dc=example,dc=com" -s baseObject \"(objectClass=*)"
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body><dsml:batchResponse xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
<dsml:searchResponse><dsml:searchResultEntry dn="dc=example,dc=com"><dsml:attr
name="objectClass"><dsml:value>domain</dsml:value><dsml:value>top</dsml:value>
</dsml:attr><dsml:attr name="dc"><dsml:value>example</dsml:value></dsml:attr>
</dsml:searchResultEntry><dsml:searchResultDone><dsml:resultCode code="0"/>
</dsml:searchResultDone></dsml:searchResponse></dsml:batchResponse>
</SOAP-ENV:Body></SOAP-ENV:Envelope>

Using the `dsmlmodify` Utility

dsmlmodify utility is a DSML-based counterpart to the ldapmodify command, and it can perform add, delete, modify, and modify DN operations over DSML. To see the usage information for this tool, run it with no arguments, as shown in this example:

$ ./dsmlmodify
usage: dsmlmodify -h http://host:port [options] -f file
where:
-h hostURL URL of the directory server
-D binddn  bind dn
-w passwd  bind password (for simple HTTP authentication)
use "-w - " to prompt for a password
-j pwfile  file where password is stored
-f file    specify the name of the file containing
the modifications

As with the dsmlsearch utility, the -h argument specifies a URL, and the output is returned in DSML form. Unlike ldapmodify, the dsmlmodify tool does not accept the changes through standard input. Changes must be specified in a file, and that file must be in DSML format instead of than LDIF, and the changes cannot contain an outer batchRequest wrapper. The following example shows a typical input file.

<addRequest dn="uid=test.user,dc=example,dc=com">
<attr name="objectClass">
<value>top</value>
<value>person</value>
<value>organizationalPerson</value>
<value>inetOrgPerson</value>
</attr>
<attr name="uid">
<value>test.user</value>
</attr>
<attr name="givenName">
<value>Test</value>
</attr>
<attr name="sn">
<value>User</value>
</attr>
<attr name="cn">
<value>Test User</value>
</attr>
<attr name="userPassword">
<value>password</value>
</attr>
</addRequest>
<modifyRequest dn="uid=test.user,dc=example,dc=com">
<modification name="description" operation="replace">
<value>This is the new description</value>
</modification>
</modifyRequest>
<modDNRequest dn="uid=test.user,dc=example,dc=com" newrdn="cn=Test User" 
 deleteoldrdn="false" newSuperior="ou=People,dc=example,dc=com" />
<delRequest dn="cn=Test User,ou=People,dc=example,dc=com" />

The following example shows the output from applying these changes. Line breaks have been added to the output to make it more readable:

$ dsmlmodify -h http://127.0.0.1:8080/dsml/DSMLServlet \ -D "cn=Directory Manager" -w password -f /tmp/test.dsml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body><dsml:batchResponse xmlns:dsml="urn:oasis:names:tc:DSML:2:0:core">
<dsml:addResponse><dsml:resultCode code="0"/></dsml:addResponse>
<dsml:modifyResponse><dsml:resultCode code="0"/></dsml:modifyResponse>
<dsml:modDNResponse><dsml:resultCode code="0"/></dsml:modDNResponse>
<dsml:delResponse><dsml:resultCode code="0"/><dsml:errorMessage>The number of
entries deleted was 1</dsml:errorMessage></dsml:delResponse></dsml:batchResponse>
</SOAP-ENV:Body></SOAP-ENV:Envelope>

$ dsmlmodify -h http://localhost:8080/dsml/DSMLServlet \ -D "cn=directory manager" -w password -f /tmp/dsml.ldif
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body><batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core">
<addResponse><resultCode code="0"/></addResponse>
<modifyResponse><resultCode code="0"/></modifyResponse>
<modDNResponse><resultCode code="0"/></modDNResponse>
<delResponse><resultCode code="0"/></delResponse></batchResponse>
</SOAP-ENV:Body></SOAP-ENV:Envelope>

Skip Navigation Links
Exit Print View
	Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1)