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.
The DSML front end is disabled by default. For information on how to enable it, refer to Configuring DSML in Sun Java System Directory Server Enterprise Edition 6.1 Administration Guide. To check whether the DSML front end is enabled, send an empty DSML batch request, as shown in Example 10–1.
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 10–2.
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/6.1 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).
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 10–3.
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 10–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\>
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/6.1 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.
Example 10–5 shows a DSML base object search request on the root DSE entry.
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\>
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/6.1 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/6.1</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\>