Directory Services

Configuring DSML Services for Windows Manually

DSML Services for Windows can be configured manually. A manual configuration is usually performed to support multiple installations of DSML Services for Windows on the same IIS server.

Manually configuring DSML Services for Windows

To configure DSML Services for Windows manually:

Install files for DSML Services for Windows
Configure IIS and Active Directory
Create the DSML virtual directory
Configure the DSML virtual directory
Modify the DSML configuration file
Test the DSML configuration

Install files for DSML Services for Windows

For more information about installing the files, see Installing DSML Services for Windows.

Configure IIS and Active Directory

Configure the server to support IIS if this has not already been done. You should also have an Active Directory domain controller running before continuing.

Create the DSML virtual directory

Start IIS services and create a new virtual directory named dsml on the Web server under the Default Web Site, with the path to directory set to C:\DSFW\bin (or to the directory you created during the setup process).
Set the Execute Permissions of the virtual directory to Scripts and Executables.
This creates the new virtual directory.

Configure the DSML virtual directory

Right-click the virtual directory, and then select Properties.
From the Directory Security property page, click on Edit in the Anonymous Access and Authentication control group box. Disable Anonymous Access.
Configure the virtual directory to support Basic authentication and Integrated Windows authentication.
Note It is highly recommended that you enable SSL if you select Basic authentication. This prevents passwords from being transmitted in plaintext.
From the Virtual Directory property page, select Configuration.
From the Mappings tab of the Application Configuration dialog box, select Add. Set the Executable to c:\dsfw\bin\adssoap.dll (or the path to adssoap.dll where it was copied). Set the Extension to .dsmlx, and then set the Verbs to Limit To: POST.
This step is optional. From the Virtual Directory property page, set the Application Protection to High or Medium isolation.

Modify the DSML configuration file

Modify the dsmlv2.config configuration file found in the %SystemRoot%\system32 directory. The generic template for the configuration file is shown below.

<extensionConfiguration>
<virtualDirectory url="virtualDirURL">
  <server>serverName</server>
  <port>portNumber</port>
  <useSigning>enableLDAPSigning</useSigning>
  <useSealing>enableLDAPSealing</useSealing>
  <readonly>enableReadOnlyMode</readOnly>
  <connectTimeout>connTime</connectTimeout>
  <operationTimeout>operTime</operationTimeout>
  <maxConnections>numberOfConnections</maxConnections>
  <chaseReferrals>chaseReferralsType</chaseReferrals>
  <sessionsMax>totalSessions</sessionsMax>
  <sessionsMaxPerIP>sessionPerIP</sessionsMaxPerIP>
  <sessionsIPMatch>useIPMatching</sessionsIPMatch>
  <sessionsAuthMatch>useCredentialMatching</sessionsAuthMatch>
  <sessionsTTL>timeToLive</sessionsTTL>
  </virtualDirectory>
</extensionConfiguration>

virtualDirURL should be filled in with the URL to the extension, without the Web server name. For example, if you create an IIS virtual directory named dsml, which allows the extension to be accessed as http://mywebserver.microsoft.com/dsml/adssoap.dsmlx, set virtualDirURL as /dsml/adssoap.dsmlx.

All of the element tags inside the <virtualDirectory> element are optional. To omit one, omit the entire line, including the surrounding XML elements. For example, to omit serverName, omit <server>serverName</server>:

serverName specifies the DNS name of the Active Directory server or domain against which to perform LDAP operations. If serverName is omitted, DSML Services for Windows connects to a domain controller for the domain to which the Web server’s computer account belongs. If a domain name is specified, it connects to a DC for that domain. If a server name is specified, it connects to that specific server.
portNumber specifies the port number on the Active Directory server to which to connect. The default is port 389.
enableLDAPSigning specifies whether the LDAP connection between the DSML Services for Windows server and the Active Directory server will use certificate signing. This option does not affect the connection between the client application and the DSML Services for Windows server. The default value is disabled, meaning digital signing is not used.
enableLDAPSealing specifies whether the LDAP connection between the DSML Services for Windows server and the Active Directory server will use data encryption. This option does not affect the connection between the client application and the DSML Services for Windows server. The default value is disabled, meaning encryption not used.
enableReadOnlyMode specifies whether read-only mode is enabled. If enabled, the DSML Services for Windows server will only process <searchRequest> and <compareRequest> operations. Other requests, for example, requests to add to, delete from, or modify the directory, will fail. The default value is false.
connTime specifies how many seconds to wait when trying to establish a LDAP connection to the Active Directory server. The default setting is no timeout period. It is recommended that you specify a timeout period.
operTime specifies how many seconds to wait for an individual LDAP operation to complete. The default is no timeout period. It is recommended that you specify a timeout period.
numberOfConnections specifies the maximum number of simultaneous LDAP connections to keep open to the Active Directory server. The default number is five. The higher this number, the greater the number of incoming DSML requests that can be simultaneously processed.
chaseReferralsType specifies the type of referral chasing used by the Active Directory server when a referral is generated. The allowable values are never, always, subordinate, and external. The default value is never, meaning referral chasing is not used.
totalSessions specifies the total number of outstanding active sessions allowed. If the total number reaches the maximum, and a client requests a new session, the server will reject all subsequent new session requests until the number of outstanding active sessions is less than the maximum number specified. The default value is 100 sessions.
sessionsPerIP specifies the number of sessions allowed for a given IP address. The default value is five (5) sessions.
useIPMatching specifies whether the server should check to determine if the IP address matches the original creator of the session when the client requests a session ID. The default value is true.
useCredentialMatching specifies whether the server should check to determine if the user credentials match those of the original creator of the session when the client requests a session ID. The default value is true.
timeToLive specifies the number of seconds the session should live before it is declared to be expired. Each client request with the session ID revitalizes the TTL. If there is no activity beyond the TTL, the session is considered to be dead. The default value is 600 seconds.

For example, using the dsml virtual directory example given previously, the following dsmlv2.config would specify that the IIS virtual directory should process requests for an Active Directory server named testdc-01.fabrikam.com. It should connect on port 389, with connection and operation timeouts of 30 seconds. It should keep up to 10 connections open simultaneously.

<extensionConfiguration>
   <virtualDirectory url="/dsml/adssoap.dsmlx">
		<server>testdc-01.fabrikam.com</server>
		<port>389</port>
		<connectTimeout>30</connectTimeout>
		<operationTimeout>30</operationTimeout>
		<maxConnections>10</maxConnections>
   </virtualDirectory>
</extensionConfiguration>

It is possible to create multiple IIS virtual directories on the Web server that use the adssoap.dsmlx extension. This can be used, for example, for sending requests to different Active Directory servers. All virtual directories on an IIS server share the same dsmlv2.config file. The IIS virtual directories must be created and configured with the proper permissions (using the steps listed previously in this topic) before the DSML Services for Windows configuration file is modified.

To configure a multiple virtual directory installation, create a separate virtualDirectory section for each virtual directory in the configuration file. For example, if you want to extend the example above to include a second virtual directory named dsml2 that sends LDAP operations to a Active Directory server named testdc-02.fabrikam.com (also on port 389, but with no connect or operation timeout, and using the default number of connections), you could create a dsmlv2.config file similar to the following.

<extensionConfiguration>
   <virtualDirectory url="/dsml/adssoap.dsmlx">
		<server>testdc-01.fabrikam.com</server>
		<port>389</port>
		<connectTimeout>30</connectTimeout>
		<operationTimeout>30</operationTimeout>
		<maxConnections>10</maxConnections>
   </virtualDirectory>
<virtualDirectory url="/dsml2/adssoap.dsmlx">
   <server>testdc-02.fabrikam.com</server>
   </virtualDirectory>
</extensionConfiguration>

The dsmlv2.config file should have its file access permissions set so that all authenticated users have read access, and only administrators and IIS administrators have read/write access. This enables the DSML Services for Windows to read the configuration file while impersonating a user, yet prevents the configuration file from being subject to either accidental or malicious changes.

Test the DSML Configuration

The DSML Services for Windows installation is now configured and ready for use. To test the installation, take the following steps:

Adjust the value of the dn in the Search.xml file to match the Active Directory domain name.
If testing a multiple virtual directory installation and the name of the virtual directory is something other than dsml, edit the dsmltest.vbs testscript accordingly. Comments in the script file will state where the appropriate changes must occur.
Run the following test script at a command prompt, using a user account that has the proper credentials to access the DSML Services for Windows server.
csript dsmltest.vbs dsmlServerName

The following code example shows a test of the installation.

 C:\DSfW>type search.xml

<se:Envelope xmlns:se="http://schemas.xmlsoap.org/soap/envelope/">
  <se:Body xmlns="urn:oasis:names:tc:DSML:2:0:core">
	 <batchRequest>
		 <searchRequest dn="dc=fabrikam,dc=com"
			 scope="baseObject"
			 derefAliases="neverDerefAliases"
			 sizeLimit="100">
			 <filter>
				 <present name="objectClass"/>
			 </filter>
			 <attributes>
					 <attribute name="dc"/>
					 <attribute name="description"/>
			 </attributes>
		 </searchRequest>
	 </batchRequest>
  </se:Body>
</se:Envelope>

C:\Program Files\Microsoft\Microsoft DSMLv2 Server>cscript dsmltest.vbs dsml01

Microsoft (R) Windows Script Host Version 5.6
Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

Connecting to DSMLv2 Server...

Constructing DSML/SOAP payloads...

Sending the request...

-------RESPONSE --------
 
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
<soap:Body>
  <batchResponse xmlns="urn:oasis:names:tc:DSML:2:0:core" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <searchResponse>
		 <searchResultEntry dn="dc=fabrikam,dc=com">
			 <attr name="dc"><value>fabrikam</value></attr>
		 </searchResultEntry>
		<searchResultDone>
				 <resultCode code="0" descr="success"/>
		</searchResultDone>
   </searchResponse>
</batchResponse></soap:Body></soap:Envelope>