Sun ONE Directory Server 5.2 Deployment Guide: Appendix A Accessing Data Using DSMLv2 Over HTTP/SOAP

Sun ONE Directory Server 5.2 Deployment Guide

Appendix A      Accessing Data Using DSMLv2 Over HTTP/SOAP

Sun ONE Directory Server 5.2 supports DSMLv2, which maps the majority of the query/update functionality of LDAP version 3 to XML, SOAP and HTTP. Being able to perform directory operations in DSMLv2 extends the reach of your directory data directly into the worlds of XML and web services. This section is designed to give you an insight into how you can perform directory operations using DSMLv2 over SOAP/HTTP and contains the following examples:

An Empty Anonymous DSML "Ping" Request

A DSML Request Issuing a User Binding

A DSML Search Request

Caution

The content-length: header in the following examples contains the exact length of the DSMLv2 request. In order for these examples to function correctly, make sure either that the editor you use respects these content lengths or that you modify them accordingly.

For a complete list of DSML related attributes and information about the DSMLv2 standard, refer to the Sun ONE Directory Server Reference Manual. For DSML related procedures refer to the Sun ONE Directory Server Administration Guide.

An Empty Anonymous DSML "Ping" Request

Before issuing DSML requests over HTTP/SOAP you need to ensure that the DSML front end is enabled by sending an empty DSML batch request to your directory. An empty DSML batch request would read as follows:

POST /dsml HTTP/1.1
content-length: 451
HOST: hostMachine
SOAPAction: ""
Content-Type: text/xml
Connection: close

<?xml version='1.0' encoding='UTF-8'?>
<soap-env:Envelope
   xmlns:xsd='http://www.w3.org/2001/XMLSchema'
   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
   xmlns:soap-env='http://schemas.xmlsoap.org/soap/envelope/'>

   <soap-env:Body>
      <batchRequest
          xmlns='urn:oasis:names:tc:DSML:2:0:core'           requestID='Ping!'>
          
      </batchRequest>
   </soap-env:Body>
</soap-env:Envelope>

The first section of this DSML request is the HTTP section:

POST /dsml HTTP/1.1
content-length: 451
HOST: hostMachine
SOAPAction: ""
Content-Type: text/xml
Connection: close

and is comprised of the HTTP method line

POST /dsml HTTP/1.1

followed by a number of HTTP headers. The HTTP method line specifies the HTTP method request and URL to be used by the DSML front end. POST is the only HTTP method request accepted by the DSML front end, whereas the /dsml URL, although the default URL for Directory Server, can be configured with any other valid URL. The HTTP headers that follow, specify the remaining details of the DSML request. The header

content-length: 451

gives the exact length of the SOAP/DSML request,and the header

HOST: hostMachine

specifies the name of the host Directory Server being contacted. The header

SOAPAction:

is mandatory and informs the directory that you want to perform a DSML request on the HTTP/SOAP stack. It may however, be left empty. The header

Content-Type: text/xml

must have a value of text/xml which defines the content as XML. Finally the header

Connection: close

specifies that the connection will be closed once the request has been satisfied, in contrast to the default HTTP/1.1 behavior that maintains connections open.

The following constitutes the SOAP/DSML section of the request:

<?xml version='1.0' encoding='UTF-8'?>
<soap-env:Envelope
   xmlns:xsd='http://www.w3.org/2001/XMLSchema'
   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
   xmlns:soap-env='http://schemas.xmlsoap.org/soap/envelope/'>

   <soap-env:Body>
      <batchRequest
          xmlns='urn:oasis:names:tc:DSML:2:0:core'           requestID='Ping!'>
          
      </batchRequest>
   </soap-env:Body>
</soap-env:Envelope>

The DSML request begins with the XML prolog header,

<?xml version='1.0' encoding='UTF-8'?>

which specifies that the request must be encoded with the UTF-8 character set, and then continues with the SOAP envelope and body element that contain the mandatory inclusion of the XML schema, XML schema instance and SOAP namespaces as follows:

<soap-env:Envelope
   xmlns:xsd='http://www.w3.org/2001/XMLSchema'
   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
   xmlns:soap-env='http://schemas.xmlsoap.org/soap/envelope/'>

   <soap-env:Body>

The DSML batch request element

      <batchRequest

marks the beginning of the DSML batch request, is immediately followed by the mandatory inclusion of the DSMLv2 namespace,

xmlns='urn:oasis:names:tc:DSML:2:0:core'.

and is optionally identified by the following request ID

requestID='Ping!'>

The empty batch request

.
is XML commented as such, and the SOAP/DSML batch request is closed using the following close batch request, close SOAP body, and close SOAP envelope elements:

      </batchRequest>
   </soap-env:Body>
</soap-env:Envelope>

Caution

Maximum limits exist for the number of clients connecting simultaneously to the directory and for the size of the DSML requests. The limit for the number of clients is managed by the ds-dsml-poolsize and ds-dsml-poolmaxsize attributes and the request size limit by the ds-dsmll-requestmaxsize attribute. For more information regarding DSML-related attributes, refer to the Sun ONE Directory Server Reference Manual.

If the DSML front end is enabled, an empty DSML response, such as the one below will be returned.

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Mon, 09 Sep 2002 13:56:49 GMT
Accept-Ranges: none
Server: Sun-ONE-Directory/5.2
Content-Type: text/xml; charset="utf-8"
Content-Length: 500

<?xml version='1.0' encoding='UTF-8' ?>
<soap-env:Envelope
   xmlns:xsd='http://www.w3.org/2001/XMLSchema'
   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
   xmlns:soap-env='http://schemas.xmlsoap.org/soap/envelope/'
   >
<soap-env:Body>
<batchResponse
   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'
   requestID='Ping!'
   >
</batchResponse>
</soap-env:Body>
</soap-env:Envelope>

However, if nothing is returned, then you can conclude that the front end is disabled.

Note
The DSML front end is disabled by default. To enable it you should change the value of the nsslapd-pluginEnabled attribute under the cn=DSMLv2-SOAP-HTTP,cn=frontends,cn=plugins,cn=config entry in the dse.ldif file to on. You can also modify the ds-hdsml-port and ds-hdsml-root attributes, but this is optional. For information on how to enable the DSML front end, refer to the Sun ONE Directory Server Administration Guide.

A DSML Request Issuing a User Binding

To issue a DSML request you can choose, as with the LDAP protocol, either to bind to the directory as a given user or access anonymously. If you want to bind to the directory as a given user, your DSML request will include an HTTP authorization header containing a uid and a password that will then be mapped to a dn.

Note
For information on how to configure the identity mapping refer to the Sun ONE Directory Server Administration Guide.

An HTTP authorization request would read as follows:

POST /dsml HTTP/1.1
content-length: 578
Content-Type: text/xml; charset="utf-8"
HOST: hostMachine
Authorization: Basic ZWFzdGVyOmVnZw==
SOAPAction: ""
Connection: close

<?xml version='1.0' encoding='UTF-8'?>
<soap-env:Envelope
   xmlns:xsd='http://www.w3.org/2001/XMLSchema'
   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
   xmlns:soap-env='http://schemas.xmlsoap.org/soap/envelope/'>
   <soap-env:Body>
     <batchRequest
        xmlns='urn:oasis:names:tc:DSML:2:0:core'
        <extendedRequest>
          <requestName>1.3.6.1.4.1.4203.1.11.3</requestName>
        </extendedRequest>
     </batchRequest>
   </soap-env:Body>
</soap-env:Envelope>

This example shows the HTTP authorization header transporting the uid easter and the password egg, which, in clear, would appear as easter:egg, and encoded in base64 as:

Authorization: Basic ZWFzdGVyOmVnZw==

Should you want to access anonymously, no HTTP authorization header including the password and uid would be required. However, it is worth bearing in mind that anonymous access is often subject to strict access controls, and that you would be likely to encounter data access restrictions. Similarly, you can issue DSML requests to perform LDAP operations by LDAP proxy. It is interesting to note that as DSML requests are managed on a batch basis, if you decide to issue requests by LDAP proxy, then the required DSML proxy authorization request must be the first in a given batch of requests.

A DSML Search Request

Once you have established that your DSML front end is enabled you can start performing directory operations. A sample DSML base object search request on the root DSE entry for the namingContexts, supportedLDAPversion, vendorName, vendorVersion, and supportedSASLMechanisms attributes would read as follows:

POST /dsml HTTP/1.1
HOST: hostMachine
Content-Length: 1081
Content-Type: text/xml
SOAPAction: ""
Connection: close

<?xml version='1.0' encoding='UTF-8'?>
<soap-env:Envelope
   xmlns:xsd='http://www.w3.org/2001/XMLSchema'
   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
   xmlns:soap-env='http://schemas.xmlsoap.org/soap/envelope/'
   >
   <soap-env:Body>
      <batchRequest
        xmlns='urn:oasis:names:tc:DSML:2:0:core'
        requestID='Batch of search requests'
        >
        <searchRequest
            dn=""
            requestID="search on Root DSE"
            scope="baseObject"
            derefAliases="neverDerefAliases"
            typesOnly="false"
            >
            <filter>
               <present name="objectClass"/>
            </filter>
            <attributes>
               <attribute name="namingContexts"/>
               <attribute name="supportedLDAPversion"/>
               <attribute name="vendorName"/>
               <attribute name="vendorVersion"/>
               <attribute name="supportedSASLMechanisms"/>
            </attributes>
        </searchRequest>
      </batchRequest>
   </soap-env:Body>
</soap-env:Envelope>

With the following attribute-data pairs:

dn=""
requestID="search on Root DSE"

this search operation requests data under the root DSE entry and is identified with an optional request ID attribute. The attribute-data pair:

scope="baseObject"

specifies that the search is a base object search while the attribute-data pair:

derefAliases="neverDerefAliases"

specifies that the aliases should not be dereferenced while searching or locating the base object of the search, which is in fact the only derefAliases value supported by Directory Server.

The attribute-data pair:

typesOnly="false"

specifies that both the attribute names and their values be returned, as opposed to typesOnly="true", which will return attribute names only. The default value for this attribute is false.

For the entry to match the filter, the presence of objectclass filter is used as follows:

<filter>
   <present name="objectClass"/>
</filter>

and is followed by the list of desired attributes:

<attributes>
   <attribute name="namingContexts"/>
   <attribute name="supportedLDAPversion"/>
   <attribute name="vendorName"/>
   <attribute name="vendorVersion"/>
   <attribute name="supportedSASLMechanisms"/>
</attributes>

Previous Contents Index Next
Copyright 2003 Sun Microsystems, Inc. All rights reserved.