|Skip Navigation Links|
|Exit Print View|
|Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1)|
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.
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.
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.
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:
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.
Deploy the DSML Gateway WAR file, as described in the following section.
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.
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:
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.
The Open LDAP/DSML Connection window opens with fields for connection information. The following figure shows typical entries.
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.
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>
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>