4 Protocol Examples

In this section, a complete session exchange is shown, consisting of the following steps:

  1. The client requests the server to create a session.

  2. The server creates a session and returns a SessionID attribute value for that session.

  3. The client requests the server to perform some operations within the context of the session.

  4. The client requests the server to terminate the session.

In this example, the DSML payload is an empty <dsml:batchRequest />, so that the only operation the server performs is to create the session.

[SOAP]

 <soap:Envelope>
   <soap:Header>
     <BeginSession xmlns="urn:schema-microsoft-com:activedirectory:dsmlv2"
       soap:mustUnderstand="1" />
   </soap:Header>
   <soap:Body>
     <dsml:batchRequest />
   </soap:Body>
 </soap:Envelope>

The server creates a session and assigns it a unique SessionID attribute value. It then sends a response to the client informing it of the SessionID of the new session.

[SOAP]

 <soap:Envelope>
   <soap:Header>
     <ad:Session xmlns:ad="urn:schema-microsoft-com:activedirectory:dsmlv2"
       ad:SessionID="12345" />
   </soap:Header>
   <soap:Body>
     <dsml:batchResponse />
   </soap:Body>
 </soap:Envelope>

The client requests a standard DSML operation. By attaching the <Session> header (section 2.2.2.2) with the previously defined SessionID, the client causes the server to perform the operation in the context of the session.

[SOAP]

 <soap:Envelope>
   <soap:Header>
     <ad:Session xmlns:ad="urn:schema-microsoft-com:activedirectory:dsmlv2"
       ad:SessionID="12345" soap:mustUnderstand="1" />
   </soap:Header>
   <soap:Body>
     <dsml:batchRequest>
       <dsml:searchRequest dn="ou=Sales,dc=fabrikam,dc=com"
        scope="baseObject"
        derefAliases="neverDerefAliases">
         <dsml:filter>
           <dsml:present name="objectclass" />
         </dsml:filter>
       </dsml:searchRequest>
     </dsml:batchRequest>
   </soap:Body>
 </soap:Envelope>

The server returns the response with a <Session> header attached.

[SOAP]

 <soap:Envelope>
   <soap:Header>
     <ad:Session xmlns:ad="urn:schema-microsoft-com:activedirectory:dsmlv2"
       ad:SessionID="12345"/>
   </soap:Header>
   <soap:Body>
     <dsml:batchResponse>
       <dsml:searchResponse>
         <dsml:searchResultEntry dn="ou=Sales,dc=fabrikam,dc=com">
           <dsml:attr name="description">
             <dsml:value>Sales force organizational unit</dsml:value>
           </dsml:attr>
         remaining attributes of the object...
         </dsml:searchResultEntry>
         <dsml:searchResultDone>
           <dsml:resultCode code="0" />
         </dsml:searchResultDone>
       </dsml:searchResponse>
     </dsml:batchResponse>
   </soap:Body>
 </soap:Envelope>

The client can continue requesting DSML operations in the context of the session by attaching <Session> headers as in the preceding example. When the client is finished, it terminates the session by sending an <EndSession> header (section 2.2.2.3).

In this example, the client also includes a <dsml:addRequest> operation inside the <dsml:batchRequest>. This operation is performed in the context of the <Session>. That is, the operation is equivalent to the client first sending a <dsml:batchRequest> that contains the <dsml:addRequest> with a <Session> header attached, followed by an empty <dsml:batchRequest> that contains an <EndSession> header.

[SOAP]

 <soap:Envelope>
   <soap:Header>
     <ad:EndSession xmlns:ad="urn:schema-microsoft-com:activedirectory:dsmlv2"
       ad:SessionID="12345" soap:mustUnderstand="1" />
   </soap:Header>
   <soap:Body>
     <dsml:batchRequest>
       <dsml:addRequest dn="ou=DSMLSamples,dc=fabrikam,dc=com">
         <dsml:attr name="objectClass">
           <dsml:value>organizationalUnit</dsml:value>
         </dsml:attr>
       </dsml:addRequest>
     </dsml:batchRequest>
   </soap:Body>
 </soap:Envelope>

The server responds as follows and includes the SessionID attribute value of the session it terminated.

 <soap:Envelope>
   <soap:Header>
     <ad:Session xmlns:ad="urn:schema-microsoft-com:activedirectory:dsmlv2"
       ad:SessionID="12345"/>
   </soap:Header>
   <soap:Body>
     <dsml:batchResponse>
       <dsml:addResponse>
         <dsml:resultCode code="0" descr="success" />
       </dsml:addResponse>
     </dsml:batchResponse>
   </soap:Body>
 </soap:Envelope>
Show: