Share via

What's New in AD DS: Active Directory Web Services

  • Article

Applies To: Windows Server 2008 R2

What does Active Directory Web Services do?

Active Directory Web Services (ADWS) in Windows Server 2008 R2 is a new Windows service that provides a Web service interface to Active Directory domains, Active Directory Lightweight Directory Services (AD LDS) instances, and Active Directory Database Mounting Tool instances that are running on the same Windows Server 2008 R2 server as ADWS. If the ADWS service on a Windows Server 2008 R2 server is stopped or disabled, client applications, such as the Active Directory module for Windows PowerShell or the Active Directory Administrative Center will not be able to access or manage any directory service instances that are running on this server.

ADWS is installed automatically when you add the AD DS or AD LDS server roles to your Windows Server 2008 R2 server. ADWS is configured to run if you make this Windows Server 2008 R2 server a domain controller by running Dcpromo.exe or if you create an AD LDS instance on this Windows Server 2008 R2 server.

Note

To use Windows Server 2008 R2 or Windows 7 client application such as the Active Directory module for Windows PowerShell or the Active Directory Administrative Center to access or manage directory service instances that are running on Windows Server 2008-based or Windows Server 2003-based computers, you can install the Active Directory Management Gateway Service. For more information, see What does the Active Directory Management Gateway Service do?

Warning

To function correctly, ADWS service requires TCP port 9389 to be open on the domain controller where ADWS service is running. If you configure your firewall by using a Group Policy object (GPO), you must update the GPO to make sure that this port is open for ADWS service.

Who will be interested in ADWS?

The following groups might be interested in ADWS in Windows Server 2008 R2:

  • Early adopters of Windows Server 2008 R2 and information technology (IT) planners and analysts who are technically evaluating Windows Server 2008 R2

  • Enterprise IT planners and designers

  • AD DS management teams

  • AD DS administrators

Are there any special considerations?

Note

If a server authentication certificate from a trusted certification authority (CA) is already present on your Windows Server 2008 R2 server with the ADWS service installed, you can skip this section.

The ADWS service exposes endpoints that support the following authentication mechanisms:

  • Windows Integrated authentication, using Kerberos authentication with credentials that can be delegated

  • Simple (plaintext user name and password) authentication

So that ADWS can expose endpoints that support simple authentication, you must request and obtain a server authentication certificate from a trusted CA in your organization—for example, a Microsoft CA—or from a trusted non-Microsoft CA on your Windows Server 2008 R2 server.

For example, suppose that you have to install a server authentication certificate for ADWS that provides a Web Service interface to an AD LDS instance that is running on a Windows Server 2008 R2 server in a Workgroup environment. In this case, simple authentication must be used, because the Kerberos authentication protocol cannot be used for authentication of Workgroup users.

This server authentication certificate will be used to authenticate the server to the client and to protect the client's user name and password on the network by encrypting the communications channel. For more information about installing and using a CA, see Certificate Services (https://go.microsoft.com/fwlink/?LinkID=48952).

Note

The certificate that you install or import must be marked for server authentication.

After you obtain the certificate from a trusted CA, you must install it on or import it to the server that is running the ADWS service. When you install or import a certificate from a trusted CA onto the Windows Server 2008 R2 server with the ADWS service installed, we recommend that you store the certificate in the local computer personal certificate store. You can use Windows Server 2008 R2 Certificates snap-in to install or import your certificates. For more information, see Certificates How To (https://go.microsoft.com/fwlink/?LinkId=99765).

After the necessary server authentication certificate is installed on Windows Server 2008 R2, you must stop and restart the ADWS service:

  • You can stop the ADWS service by running the following command at a command prompt: net stop ADWS.

  • You can start the ADWS service by running the following command at a command prompt: net start ADWS.

What new functionality does ADWS provide?

In ADWS, there are a number of configuration parameters that determine how ADWS in Windows Server 2008 R2 handles the traffic that administrators generate. Administrators can manage AD DS domains, AD LDS instances, and Active Directory Database Mounting Tool instances by using applications such as the Active Directory module or Active Directory Administrative Center. These configuration parameters are stored in the Microsoft.ActiveDirectory.WebServices.exe.config file, under %WINDIR%\ADWS directory.

You can adjust these configuration parameters by editing the Microsoft.ActiveDirectory.WebServices.exe.config file to accommodate traffic that is directed at the ADWS service in their Active Directory environments. Any changes that you make to the ADWS configuration parameters on a given domain controller affect only the ADWS service that is running on this particular domain controller. In other words, changes that you make to the Microsoft.ActiveDirectory.WebServices.exe.config file on a domain controller in a given domain or forest do not replicate to other domain controllers in this domain or forest.

The following table lists the names, default values, and descriptions of the ADWS configuration parameters that determine how the ADWS service handles the traffic that is generated by administrators who are managing AD DS and AD LDS instances and Active Directory Database Mounting Tool instances by using the Active Directory module or Active Directory Administrative Center.

Important

We recommend that you not change the default values of these parameters unless they prevent you from efficiently administering directory service instances that are supported by the ADWS service through the Active Directory module or Active Directory Administrative Center.

Parameter name Default value Description

MaxConcurrentCalls

32

Specifies the maximum number of simultaneous service requests that the ADWS service is configured to process at a given time. Set a higher value for this parameter if the ADWS service on your Windows Server 2008 R2 server must be able to process more than 32 service requests at any given time.

MaxConcurrentSessions

500

Specifies the maximum number of client sessions that the ADWS service can accept at any given time. Set this parameter to a higher value if the ADWS service on your Windows Server 2008 R2 server must be able to accept more than 500 concurrent client sessions at any given time.

MaxReceivedMessageSize

1 MB

Specifies the maximum message request size, in megabytes (MB), that a client computer can send to the directory service instances that the ADWS service supports. This setting can affect the memory consumption of the ADWS service. For example, if MaxConcurrentCalls is set to 32 and MaxReceivedMessageSize is set to 1 MB, the ADWS service is configured to process a maximum of 32 MB in client message requests at any given time.

MaxStringContentLength

32 KB

Specifies the maximum string size, in kilobytes (KB) of a Lightweight Directory Access Protocol (LDAP) attribute that the ADWS service is configured to process in a message request that a client computer sends to a directory service instance that the ADWS service supports. Increasing this value can increase the maximum possible memory consumption of the ADWS service.

MaxPoolConnections

10

Specifies the maximum number of LDAP connections for each directory service instance that is used by the ADWS service that is running on a given Windows Server 2008 R2 server.

For example, if MaxPoolConnections on a particular Windows Server 2008 R2 server is set to 10 and there are 3 directory service instances running on this server, ADWS uses a maximum of 10 LDAP connections to each of these directory service instances to process requests that are sent to the ADWS service. Along with MaxConcurrentCalls, this can affect the maximum number of simultaneous requests that the ADWS service can process. Set this parameter to a higher value if you notice that client service requests are timing out while they wait for an LDAP connection to be available to process their request.

Note
To improve performance, the ADWS service on a Windows Server 2008 R2 server maintains a separate LDAP connection pool for every directory service instance that is running on this server. For example if your Windows Server 2008 R2 server is a domain controller (and is, therefore, running the AD DS server role) and also a global catalog server and if it is running two AD LDS instances and one Active Directory Database Mounting Tool instance (a total of five directory service instances), the ADWS service on this Windows Server 2008 R2 server maintains five separate LDAP connection pools. Because a global catalog does not share the same LDAP port as AD DS, it is considered a separate directory instance.

MaxPercentageReservedConnections

50%

Specifies the percentage of LDAP connections that are reserved for performing query operations for each directory service instance that the ADWS service supports on a given Windows Server 2008 R2 server. Set this parameter to a higher percentage if the ADWS service on this Windows Server 2008 R2 server is used mostly for running queries.

MaxConnectionsPerUser

5

Specifies the maximum number of LDAP connections (to a single directory service instance) that the ADWS service permits to be used at one time for operations that are associated with a single set of client credentials (one user). Set this parameter to a higher value if you are experiencing more than five concurrent client requests by one user to a single directory service instance running on your Windows Server 2008 R2 server. The value of MaxConnectionsPerUser cannot be greater than the value of MaxPoolConnections. If the value of MaxConnectionsPerUser is equal to the value of MaxPoolConnections, it will allow a single set of client credentials (for a single client computer) to consume all available LDAP connections for a given directory service instance.

MaxEnumContextExpiration

30 minutes

Specifies the maximum allowed time period during which the ADWS service processes and retrieves the results of a query request from a client computer.

Warning

Changing the default value of this parameter is strongly discouraged. Most of the search results are returned within 30 minutes.

MaxPullTimeout

2 minutes

Specifies the maximum allowed time-out value that a client computer can set when it retrieves one page of search results. Set this parameter to a higher value if slow wide area network (WAN) traffic results in a time-out value for returning one page of search results that is longer than two minutes

Note

The ADWS service processes search requests from client computers in the following manner:

  • A client submits a search request.

  • The ADWS service establishes a search context and returns a search context ID to the client computer.

  • Using this search context ID, the client computer issues a page request to extract the search results specifying how many LDAP objects can be returned per page.

MaxPullTimeout controls the maximum amount of time a client can ask the ADWS service to spend retrieving a page of results, while MaxEnumContextExpiration is the maximum time that the search context can be kept open.

MaxEnumCtxsPerSession

5

Specifies the maximum number of search requests (search contexts) that can be submitted over a single client session to the ADWS service.

MaxEnumCtxsTotal

100

Specifies the maximum number of search requests (search contexts) that can be submitted over all active client sessions to the ADWS service.

MaxGroupOrMemberEntries

5000

Specifies the maximum number of group members (recursive or non-recursive), group memberships, and authorization groups that can be retrieved by the Active Directory module Get-ADGroupMember, Get-ADPrincipalGroupMembership, and Get-ADAccountAuthorizationGroup cmdlets. Set this parameter to a higher value if you anticipate these cmdlets to return more than 5000 results in your environment.

Note

This setting can affect the memory consumption of the ADWS service.

Note

This configuration parameter is applicable only to the three Active Directory module cmdlets mentioned above.

Note

If your operation returns an exceptionally large results set, you might run into a non-configurable 5-minute timeout.

OperationTimeout

2 minutes

Specifies the timeout limit for any ADWS service-based query request. Set this parameter to a higher value if you expect your query to return an exceptionally large results set that might take longer than 2 minutes to retrieve.

To change the values of the ADWS configuration parameters, modify the Microsoft.ActiveDirectory.WebServices.exe.config file in any text editor and then save it in the %WINDIR%\ADWS directory of your Windows Server 2008 R2 server. After the Microsoft.ActiveDirectory.WebServices.exe.config file is modified, we recommend that you stop and restart the ADWS service:

  • You can stop the ADWS service by running the net stop ADWS command at a command prompt.

  • You can start the ADWS service by running the net start ADWS command at a command prompt.

Note

Several of the ADWS service configuration parameters in this table affect bandwidth throttling on a Windows Server 2008 R2 server on which the ADWS service is running. We recommend that administrators modify the default values of only the following parameters: MaxConcurrentCalls, MaxConcurrentSessions, MaxReceivedMessageSize, and MaxStringContentLength.

How should I prepare to deploy ADWS?

The ADWS service is installed automatically when you add the AD DS or AD LDS server roles to your Windows Server 2008 R2 server. The ADWS service is configured to run if you make this Windows Server 2008 R2 server a domain controller by running Dcpromo.exe or if you create an AD LDS instance on this Windows Server 2008 R2 server.

Which editions include ADWS?

ADWS is available in the following editions of Windows Server 2008 R2:

  • Windows Server 2008 R2 Standard

  • Windows Server 2008 R2 Enterprise

  • Windows Server 2008 R2 Datacenter

ADWS is not available in the following editions of Windows Server 2008 R2:

  • Windows Server 2008 R2 for Itanium-Based Systems

  • Windows Web Server 2008 R2

What does the Active Directory Management Gateway Service do?

Active Directory Management Gateway Service runs as the Windows Server 2008 R2 ADWS service and provides the same functionality.

You can download and install the Active Directory Management Gateway Service on servers and domain controllers running the following operating systems:

  • Windows Server® 2003 R2 with Service Pack 2 (SP2)

  • Windows Server 2003 SP2

  • Windows Server 2008

  • Windows Server 2008 SP2

To download Active Directory Management Gateway Service, see Active Directory Management Gateway Service (Active Directory Web Service for Windows Server 2003 and Windows Server 2008) (https://go.microsoft.com/fwlink/?LinkID=144513).

After it is installed on any of these operating systems, Active Directory Management Gateway Service provides the same functionality to domain controllers that are running Windows Server® 2003 R2 with SP2, Windows Server 2003 SP2, Windows Server 2008, and Windows Server 2008 SP2 operating systems as ADWS provides for domain controllers that are running Windows Server 2008 R2 operating system.

Note

The only difference between the functionality that ADWS provides for domain controllers that are running Windows Server 2008 R2 operating system and the functionality that the Active Directory Management Gateway Service provides to domain controllers that are running Windows Server® 2003 R2 with SP2, Windows Server 2003 SP2, Windows Server 2008, and Windows Server 2008 SP2 operating systems is that Active Directory Management Gateway Service does not support instances of the Active Directory Database Mounting Tool running on Windows Server 2008-based servers.

If Active Directory Management Gateway Service on your server is stopped or disabled, client applications, such as the Active Directory module for Windows PowerShell or the Active Directory Administrative Center will not be able to access or manage any directory service instances that are running on this server.