Sun Directory Server Enterprise Edition 7.0 Reference

Accessing the Directory Using DSMLv2

The following examples indicate how to use DSML requests to access and search the directory.

Note that the content-length: header in these examples contains the exact length of the DSMLv2 request. For these examples to function correctly, ensure that the editor you use respects these content lengths, or that you modify them accordingly.

An Empty Anonymous DSML Ping Request

The DSML front end is disabled by default. For information on how to enable it, refer to Configuring DSML in Sun Directory Server Enterprise Edition 7.0 Administration Guide. To check whether the DSML front end is enabled, send an empty DSML batch request, as shown in Example 13–1.

Example 13–1 Empty Anonymous DSML Request

POST /dsml HTTP/1.1
 content-length: 451
 HOST: hostname
 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!’\>
           <!-- empty batch request --\>
      </batchRequest\>
    </soap-env:Body\>
 </soap-env:Envelope\>

The first section of this DSML request contains 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. The /dsml URL is the default URL for Directory Server, but can be configured with any other valid URL. The HTTP headers that follow, specify the remaining details of the DSML request.

content-length: 451specifies the exact length of the SOAP/DSML request
HOST: hostnamespecifies the name of the host Directory Server being contacted.
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.
Content-Type: text/xmlmust have a value of text/xml which defines the content as XML.
Connection: closespecifies that the connection will be closed once the request has been satisfied. The default HTTP/1.1 behavior is to maintain the connection open.

The remainder of the request is the SOAP/DSML section. The DSML request begins with the XML prologue header:
```
<?xml version=’1.0’ encoding=’UTF-8’?\>
```
This specifies that the request must be encoded with the UTF-8 character set. The header is followed by the SOAP envelope and body elements that contain the mandatory inclusion of the XML schema, XML schema instance and SOAP name spaces.

The DSML batch request element marks the beginning of the DSML batch request, and is immediately followed by the mandatory inclusion of the DSMLv2 namespace:
```
xmlns=’urn:oasis:names:tc:DSML:2:0:core’.
```
The request is optionally identified by the following request ID
```
requestID=’Ping!’
```
The empty batch request
```
<!-- empty batch request --\>
```
is XML commented as such, and the SOAP/DSML batch request is closed using the close batch request, close SOAP body, and close SOAP envelope elements.

If the DSML front end is enabled, an empty DSML response is returned, as shown in Example 13–2.

Example 13–2 Empty Anonymous DSML Response

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Mon, 11 Dec 2006 13:56:49 GMT
Accept-Ranges: none
Server: Sun-Java(tm)-System-Directory/7.0
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\>

If nothing is returned, you can conclude that the front end is disabled.

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 specified by the dsml-max-parser-count and dsml-min-parser-count server properties and the request size limit by the server property dsml-request-max-size. See server(5dsconf).

Issuing a DSML Request to Bind as a Particular User

To issue a DSML request you can bind to the directory as a specified user or anonymously. To bind as a specified user, the request must include an HTTP authorization header containing a UID and a password that are mapped to a DN, as shown in Example 13–3.

Example 13–3 DSML Extended Operation: Bind as a Particular User

POST /dsml HTTP/1.1
content-length: 578
content-Type: text/xml; charset="utf-8"
HOST: hostname
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\>

In this example the HTTP authorization header transports the user ID easter and the password egg, which, in clear, appears as easter:egg, and encoded in base64 as Authorization: Basic ZWFzdGVyOmVnZw==.

The <extendedRequest\> tag is used to specify an LDAP Extended Operation. The <requestName\> tag is used to specify the OID of the extended operation. In this example, the OID 1.3.6.1.4.1.4203.1.11.3 identifies the whoami extended operation.

The response to the DSML extended operation shows the DN of the user that made the bind request. In Example 13–4, the whoami response, which contains the DN, is shown in the response line.

<response\>dn:uid=easter,ou=people,dc=example,dc=com</response\>

Example 13–4 Response to DSML Extended Operation

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Fri, 15 Dec 2006 09:15:09 GMT
Accept-Ranges: none
Server: Sun-Java(tm)-System-Directory/7.0
Content-Type: text/xml; charset="utf-8"
Content-Length: 697

<?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’
   \>
   <extendedResponse\>
      <resultCode code=’0’ descr=’success’/\>
   <responseName\>1.3.6.1.4.1.4203.1.11.3</responseName\>
   <response\>dn:uid=easter,ou=people,dc=example,dc=com</response\>
   </extendedResponse\>
</batchResponse\>
</soap-env:Body\>
</soap-env:Envelope\>

For anonymous access, no HTTP authorization header is required, although anonymous access is often subject to strict access controls, and possibly to data access restrictions. Similarly, you can issue DSML requests to perform LDAP operations by LDAP proxy.

Because DSML requests are managed on a batch basis, if you issue requests by LDAP proxy, the required DSML proxy authorization request must be the first in a given batch of requests.

A DSML Search Request

Example 13–5 shows a DSML base object search request on the root DSE entry.

Example 13–5 DSML Search Request

POST /dsml HTTP/1.1
HOST: hostname
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\>

dn=""requestID="search on Root DSE"specifies that the search operation requests data under the root DSE entry (empty DN) and is identified with an optional request ID attribute.
scope="baseObject"specifies that the search is a base object search.
derefAliases="neverDerefAliases"specifies that the aliases should not be dereferenced while searching or locating the base object of the search. This is the only derefAliases value supported by Directory Server.
typesOnly="false"specifies that both the attribute names and their values be returned. typesOnly="true" would 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\>
```
This is equivalent to the LDAP filter string (objectclass=*). The filter 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\>
```

Example 13–6 DSML Search Response

HTTP/1.1 200 OK
Cache-control: no-cache
Connection: close
Date: Fri, 15 Dec 2006 09:21:43 GMT
Accept-Ranges: none
Server: Sun-Java(tm)-System-Directory/7.0
Content-Type: text/xml; charset="utf-8"
Content-Length: 1287

<?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=’Batch of search requests’
   \>
   <searchResponse requestID=’search on Root DSE’\>
   <searchResultEntry\>
      <attr name=’namingContexts’\>
      <value\>dc=example,dc=com</value\>
      </attr\>
      <attr name=’supportedLDAPVersion’\>
      <value\>2</value\>
      <value\>3</value\>
      </attr\>
      <attr name=’vendorName’\>
      <value\>Sun Microsystems, Inc.</value\>
      </attr\>
      <attr name=’vendorVersion’\>
      <value\>Sun-Java(tm)-System-Directory/7.0</value\>
      </attr\>
      <attr name=’supportedSASLMechanisms’\>
      <value\>EXTERNAL</value\>
      <value\>GSSAPI</value\>
      <value\>DIGEST-MD5</value\>
      </attr\>
   </searchResultEntry\>
   <searchResultDone\>
      <resultCode code=’0’ descr=’success’/\>
   </searchResultDone\>
   </searchResponse\>
</batchResponse\>
</soap-env:Body\>
</soap-env:Envelope\>