Configure IIS 7 for Web Synchronization
Applies to:
SQL Server
The procedures in this topic will guide you through the process of manually configuring Microsoft Internet Information Services (IIS) version 7 and higher for use with Web synchronization for merge replication.
Configuring IIS 7 or higher is the first of three steps needed to enable Web synchronization.
For an overview of the entire configuration process, see Configure Web Synchronization.
Important
Make sure that your application uses only .NET Framework 2.0 or later versions, and that earlier versions of the .NET Framework are not installed on the IIS server. Earlier versions of the .NET Framework can cause errors, such as: "The format of a message during Web synchronization was invalid. Ensure that replication components are properly configured at the Web server."
To use Web synchronization, you must configure IIS by completing the following steps. Each step is described in detail in this topic.
Install and configure the Microsoft SQL Server Replication Listener on the computer that is running IIS.
Configure Transport Layer Security (TLS), previously known as Secure Sockets Layer (SSL). TLS is required for communication between IIS and all subscribers.
Configure IIS authentication.
Configure an account and set permissions for the SQL Server Replication Listener.
Installing the SQL Server Replication Listener
Web synchronization is supported on IIS, beginning with version 5.0. The Configure Web Synchronization Wizard of IIS version 5 and 6, is not available with IIS version 7.0 and higher. Beginning with SQL Server 2012, to use the web sync component on IIS server, you should install SQL Server with replication. This can be the free SQL Server Express edition.
To install and configure the SQL Server Replication Listener
Install SQL Server replication on the IIS computer.
Create a new file directory for replisapi.dll on the computer that is running IIS. You can create the directory wherever you want, but we recommend that you create the directory under the <drive>:\Inetpub directory. For example, create the directory <drive>:\Inetpub\SQLReplication\.
Copy replisapi.dll from the directory <drive>:\Program Files\Microsoft SQL Server\nnn\com\ to the file directory that you created in step 1.
Register replisapi.dll:
Click Start, and then click Run. In the Open box, enter cmd, and then click OK.
In the directory created in step 1, execute the following command:
regsvr32 replisapi.dll
Create a new Web site for replication or use an existing site. This Web site will be accessed by replication components during synchronization. Procedures in this topic will assume the Default Web Site. For more information about how to create Web sites, see the IIS documentation
Create a virtual directory in IIS. The virtual directory should be created under the Web site that you created in step 4 and map it to the directory created in step 1. Be as restrictive as possible when you assign permissions to this directory. You must select at least Read and Execute permissions.
In Internet Information Services (IIS) Manager, in the Connections pane, right-click Default Web Site, and then select Add Virtual Directory.
For Alias, enter SQLReplication.
For Physical Path, enter <drive>:\Inetpub\SQLReplication\, and then click OK.
Configure IIS to enable replisapi.dll to execute.
In Internet Information Services (IIS) Manager, click Default Web Site.
In the center pane, click Handler Mappings.
In the Actions pane, click Add Module Mapping.
For Request Path, enter replisapi.dll.
From the Module drop-down list, select IsapiModule.
For Executable, enter <drive>:\Inetpub\SQLReplication\replisapi.dll.
For Name, enter Replisapi.
Click the Request Restrictions button, click the Access tab, and then click Execute.
Click OK to close the Request Restrictions dialog box, and then click OK again to close the Add Module Mapping dialog box. When you are prompted to allow the ISAPI extension, click Yes to add the extension.
Verify that Replisapi.dll is listed under the Enabled handler mappings. If it is in the Disabled list, right-click the Replisapi entry and then click Edit Feature Permissions. Check the Execute box, and then click OK.
Configuring IIS Authentication
When subscriber computers connect to IIS, IIS must authenticate the subscribers before they can access resources and processes. Authentication can be applied to the whole Web site or to the virtual directory that you created.
We recommend that you use Basic Authentication with TLS. TLS is required, regardless of the type of authentication that is used.
To Configure IIS Authentication
In Internet Information Services (IIS) Manager, click Default Web Site.
In the middle pane, double-click Authentication.
Right-click Anonymous Authentication, and then choose Disable.
Right-click Basic Authentication, and then choose Enable.
Configuring Secure Sockets Layer
To configure TLS, specify a certificate to be used by the computer running IIS. Web synchronization for merge replication supports using server certificates, but not client certificates. To configure IIS for deployment, you must first obtain a certificate from a certification authority (CA). For more information about certificates, see the IIS documentation.
After you install the certificate, you must associate the certificate with the Web site that is used by Web synchronization. For development and testing, you can specify a self-signed certificate. IIS 7 can create a certificate for you and register it on your computer.
The difference between deploying for production and the procedures given here is that in production and pre-production testing, you would use a certificate issued by a CA instead of a self-signed certificate.
Important
A self-signed certificate is not recommended for a production installation. Self-signed certificates are not secure. Use self-signed certificates for development and testing only.
To configure TLS, you will perform the following steps:
Configure the Web site to require TLS and ignore client certificates.
Obtain a certificate from a CA or create a self-signed certificate.
Bind the certificate to the replication Web site.
To require SSL security for a Web site
In Internet Information Services (IIS) Manager, expand the local server node, and then click the Default Web Site (or your Web synchronization site if it is different from the default Web site).
In the middle pane, double-click SSL Settings.
Check the Require SSL option. Under Client certificates, verify that the Ignore button is selected.
To create a self-signed certificate for testing
In Internet Information Services (IIS) Manager, click the local server node, and then in the center pane, double-click on Server Certificates.
In the Actions pane, click Create Self-Signed Certificate.
In the Create Self-Signed Certificate dialog box, enter a name for the certificate, and then click OK.
To bind a certificate to a Web site
In the Connections pane, click the Default Web Site (or your Web synchronization site, if it is different from the default Web site).
In the Actions pane, click Bindings, and then click Add. The Add Site Binding dialog box will appear.
From the Type drop-down list, select https. Leave the default settings for IP address and Port.
From the SSL certificate drop-down list, select the certificate created in "To create a self-signed certificate for testing," click OK, and then click Close.
To test the certificate
In Internet Information Services (IIS) Manager, click Default Web Site.
From the Actions pane, click Browse *:443(https).
Internet Explorer will open and display a message that "There is a problem with this website's security certificate." This warning tells you that the associated certificate was not issued by a recognized CA and might not be trustworthy. This is an expected warning, so click Continue to this website (not recommended).
If you are prompted to Connect to localhost, enter a user name and password to proceed. You should see the default page for the Web site.
Setting Permissions for the SQL Server Replication Listener
When a subscriber computer connects to the computer running IIS, the subscriber is authenticated by using the type of authentication specified when you configured IIS. After IIS authenticates the subscriber, IIS checks whether the subscriber is authorized to invoke SQL Server replication. You control the users that can invoke SQL Server replication by setting permissions for replisapi.dll. Properly configuring permissions is necessary to prevent unauthorized access to SQL Server replication.
To configure the minimum permissions for the account under which the SQL Server Replication Listener runs, complete the following procedure. The steps in the following procedure apply to Microsoft Windows Server 2008 running IIS 7.0.
In addition to performing the following steps, make sure that the required logins are in the publication access list (PAL). For more information about the PAL, see Secure the Publisher.
Important
The account created in this section is the account that will connect to the Publisher and Distributor during synchronization. This account must be added as a SQL Login account on the distribution and publication server.
The account used for the SQL Server Replication Listener must have permissions as described in the Merge Agent Security topic, in the "Connect to the Publisher or Distributor" section.
In summary, the account must:
Be a member of the Publication Access List (PAL).
Be mapped to a login associated with a user in the publication database.
Be mapped to a login associated with a user in the distribution database.
Have Read permissions on the snapshot share.
To configure the account and permissions
Create a local account on the computer running IIS:
Open Server Manager. From the Start menu, right-click Computer, and then click Manage.
In Server Manager, expand Configuration, and then expand Local Users and Groups.
Right-click Users, and then click New User.
Enter a user name and a strong password. Clear User must change password at next logon.
Click Create, and then click Close.
Add the account to the IIS_IUSRS group:
In Server Manager, expand Configuration, expand Local Users and Groups, and then click Groups.
Right-click IIS_IUSRS, and then click Add to Group.
In the IIS_IUSRS Properties dialog box, click Add.
In the Select Users, Computers, or Groups dialog box, add the account created in step 1.
Verify that From this location displays the name of the local computer (not a domain). If this field does not display the local computer name, click Locations. In the Locations dialog box, select the local computer, and then click OK.
In the Select Users dialog box and the IIS_IUSRS Properties dialog box, clickOK.
Grant minimum account permissions on the folder that contains replisapi.dll:
In Windows Explorer, right-click the folder that you created for replisapi.dll, and then click Properties.
On the Security tab, click Edit.
In the Permissions for <foldername> dialog box, click Add to add the account that you created in step 1.
Verify that From this location displays the name of the local computer (not a domain). If this field does not display the local computer name, click Locations. In the Locations dialog box, select the local computer, and then click OK.
Verify that the account is granted only Read, Read & Execute, and List Folder Contents permissions.
Select any users or groups that do not require access to the directory, click Remove, and then click OK.
Create an application pool in Internet Information Services (IIS) Manager:
In Internet Information Services (IIS) Manager, in the Connections pane, expand the local server node.
Right-click Application Pools, and then click Add Application Pool.
Enter a name for the application pool, leave the default values for the remaining fields, and then click OK.
Note
If you anticipate having more than two concurrent synchronization clients, you might want to create a web garden. For more information, see "Creating a Web Garden" in Configure Web Synchronization.
Associate the account with the application pool:
In Internet Information Services (IIS) Manager, expand the local server node, and then click on Application Pools.
Right-click the application pool that you created, and then click Set Application Pool Defaults.
In the Application Pool Defaults dialog box, scroll down to the Process Model section, and then click the Identity field.
Click the ellipsis button on the right side of the Identity row.
Click the Custom Account radio button, and then click Set.
In the User name and Password fields, enter the account and password that were created in step 1, and then click OK.
Click OK to close the Application Pool Identity dialog box, and then click OK again to close the Application Pool Defaultsdialog box.
Associate the application pool with the replication Web site:
In Internet Information Services (IIS) Manager, expand the local server node, and then click on the Default Web Site (or your Web synchronization site if it is different from the default Web site).
In the Actions pane, under Manage Web Site, click Advanced Settings.
In the Advanced Settings dialog box, click on the ellipsis button to the right of Application Pool.
From the Application pool drop-down list, select the application pool you created in step 4, and then click OK.
Click OK again to close Advanced Settings.
Testing the Connection to replisapi.dll
Run Web synchronization in diagnostic mode to test the connection to the computer running IIS and to make sure that the TLS/SSL certificate is properly installed. To run Web synchronization in diagnostic mode, you must be an administrator on the computer running IIS.
To test the connection to replisapi.dll
Make sure that local area network (LAN) settings at the Subscriber are correct:
In Microsoft Internet Explorer, on the Tools menu, click Internet Options.
On the Connections tab, click LAN Settings.
If a proxy server is not used on the LAN, clear Automatically Detect Settings and Use a proxy server for your LAN.
If a proxy server is used, click Use a proxy server for your LAN and Bypass proxy server for local addresses, and then click OK.
At the Subscriber, in Internet Explorer, connect to the server in diagnostic mode by appending
?diag
to the address for the replisapi.dll. For example:https://server.domain.com/directory/replisapi.dll?diag
.Note
In the example above, server.domain.com should be replaced with the exact Issued To name listed under the Server Certificates section in IIS Manager.
If the certificate that you specified for IIS is not recognized by the Windows operating system, the Security Alert dialog box appears. This alert might occur because the certificate is a test certificate or the certificate was issued by a certification authority (CA) that Windows does not recognize.
Note
If this dialog box does not appear, make sure that the certificate for the server that you are accessing has been added to the certificate store at the Subscriber as a trusted certificate. For more information about exporting certificates, see the IIS documentation.
In the Security Alert dialog box, click View Certificate.
In the Certificate dialog box, on the General tab, click Install Certificate.
Complete the Certificate Import Wizard, accepting the defaults.
In the Security Warning dialog box, click Yes.
In the Certificate Import Wizard confirmation dialog box, click OK.
Close the Certificate dialog box.
In the Security Alert dialog box, click Yes.
Note
Certificates are installed for users. This process must be performed for each user that will synchronize with IIS.
In the Connect to <ServerName> dialog box, specify the login and password that the Merge Agent will use to connect to IIS. These credentials will also be specified in the New Subscription Wizard.
In the Internet Explorer window called SQL Websync diagnostic information, verify that the value in each Status column on the page is SUCCESS.
Make sure that the certificate is installed correctly on the Subscriber:
Close and then reopen Internet Explorer.
Connect to the server in diagnostic mode. If the certificate is installed properly, the Security Alert dialog box will not appear. If the dialog box appears, the Merge Agent will fail when it tries to connect to the computer that is running IIS. You must make sure that the certificate for the server that you are accessing has been added to the certificate store at the Subscriber as a trusted certificate. For more information about exporting certificates, see the IIS documentation.
See Also
Web Synchronization for Merge Replication
Configure Web Synchronization