Building Secure ASP.NET Applications: Authentication, Authorization, and Secure Communication

How To: Call a Web Service Using SSL from ASP.NET 1.1

J.D. Meier, Alex Mackman, Michael Dunner, and Srinath Vasireddy
Microsoft Corporation

Published: November 2002

Last Revised: January 2006

Applies to:

• ASP.NET 1.1
• Internet Information Services (IIS) 5.0 and 5.1
• Microsoft® Windows Server™ 2000

See the "patterns & practices Security Guidance for Applications Index" for links to additional security resources.

See the Landing Page for a starting point and complete overview of Building Secure ASP.NET Applications.

Summary: Secure Sockets Layer (SSL) encryption can be used to guarantee the integrity and confidentiality of the messages passed to and from a Web service.

This How To shows you how to use SSL with Web services. (7 printed pages)

Contents

Summary of Steps Step 1. Install Server Certificates on the Web Server Step 2. Create a Simple Web Service Step 3. Configure the Web Service Virtual Directory to Require SSL Step 4. Test the Web Service Using a Browser Step 5. Install the Certificate Authority's Certificate on the Client Computer Step 6. Develop a Web Application to Call the Serviced Component
Additional Resources

You can configure a Web service to require Secure Sockets Layer (SSL) to protect sensitive data sent between the client and the service. SSL provides:

• Message integrity. This ensures that messages are not modified while in transit.
• Message confidentiality. This ensures that messages remain private while in transit.

This How To describes how to configure a Web service to require SSL and how to call the Web service from an ASP.NET client application by using the HTTPS protocol.

Summary of Steps

This article includes the following steps:

• Step 1. Install Server Certificates on the Web Server
• Step 2. Create a Simple Web Service
• Step 3. Configure the Web Service Virtual Directory to Require SSL
• Step 4. Test the Web Service Using a Browser
• Step 5. Install the Certificate Authority's Certificate on the Client Computer
• Step 6. Develop a Web Application to Call the Serviced Component

Step 1. Install Server Certificates on the Web Server

For information about installing Web server certificates on a Web server, see How To: Set Up SSL on a Web Server.

Step 2. Create a Simple Web Service

To create a simple Web service on the Web service host computer

1. Start Visual Studio .NET and create a new C# ASP.NET Web Service application called SecureMath.

2. Rename service1.asmx as math.asmx.

3. Open math.asmx.cs and rename the Service1 class as math.

4. Add the following Web method to the math class.

    [WebMethod]
   public long Add(long operand1, long operand2)
   {  
     return (operand1 + operand2);
   }
   

5. To create the Web service, click BuildSolution on the Build menu.

Step 3. Configure the Web Service Virtual Directory to Require SSL

Your Web service runs on Internet Information Services (IIS) and relies on IIS to provide SSL support.

This procedure assumes that you have a valid server certificate installed on your Web server. For more information about installing Web server certificates, see How To: Set Up SSL on a Web Server.

To use IIS to configure your Web service's virtual directory for SSL

1. On the Web service host computer, start IIS.

2. Navigate to the SecureMath virtual directory.

3. Right-click SecureMath, and then click Properties.

4. Click the Directory Security tab.

5. Under Secure communications, click Edit.

   If Edit is unavailable, it is likely that a Web server certificate is not installed.

6. Select the Require secure channel (SSL) check box.

7. Click OK, and then OK again.

8. In the Inheritance Overrides dialog box, click Select All, and then click OK to close the SecureMath properties dialog box.

   This applies the new security settings to all subdirectories in the virtual directory root.

Step 4. Test the Web Service Using a Browser

This procedure ensures that the Web server certificate is valid and has been issued by a Certification Authority (CA) that is trusted by the client computer.

To call the Web service using SSL from Internet Explorer

1. Start Internet Explorer on the client computer and browse (using HTTPS) to the Web service. For example:

   https://WebServer/securemath/math.asmx
   

   The Web service test page should be displayed by the browser.

2. If the Web service test page is displayed successfully, close Internet Explorer and go to Procedure 5, "Develop a Web Application to Call the Serviced Component."

3. If the Security Alert dialog box, as illustrated in Figure 1, is displayed, click View Certificate to see the identity of the issuing CA for the Web server certificate. You must install the CA's certificate on the client computer. This is described in Procedure 4, "Install the Certificate Authority's Certificate on the Client Computer."

4. Close Internet Explorer.

   

   Figure 1. Security Alert dialog box

Step 5. Install the Certificate Authority's Certificate on the Client Computer

This procedure installs the issuing CA's certificate on the client computer as a trusted root certificate authority. The client computer must trust the issuing CA in order to accept the server certificate without displaying the Security Alert dialog box.

If you use Microsoft Certificate Services as a CA within your Windows domain

Perform this procedure only if your Web server certificate was issued by a Microsoft Certificate Services CA. Otherwise, if you have the CA's .cer file, go to Step 8.

1. Start Internet Explorer and browse to http:// hostname/certsrv, where hostname is the name of the computer where Microsoft Certificate Services that issued the server certificate is located.

2. Click Retrieve the CA certificate or certificate revocation list, and then click Next.

3. Click Install this CA certification path.

4. In the Root Certificate Store dialog box, click Yes.

5. Browse to Web service using HTTPS. For example:

   https://WebServer/securemath/math.asmx
   

   The Web service test page should now be correctly displayed by the browser, without a Security Alert dialog box.

   You have now installed the CA's certificate in your personal trusted root certificate store. To be able to call the Web service successfully from an ASP.NET page, you must add the CA's certificate to the computer's trusted root store.

6. Repeat Steps 1 and 2, click Download CA certificate, and then save it to a file on your local computer.

7. Now perform the remaining steps, if you have the CA's .cer certificate file.

8. On the taskbar, click Start, and then click Run.

9. Type mmc, and then click OK.

10. On the Console menu, click Add/Remove Snap-in.

11. Click Add.

12. Select Certificates, and then click Add.

13. Select Computer account, and then click Next.

14. Select LocalComputer: (the computer this console is running on), and then click Finish.

15. Click Close, and then OK.

16. Expand Certificates (Local Computer) in the left pane of the MMC snap-in.

17. Expand Trusted Root Certification Authorities.

18. Right-click Certificates, point to All Tasks, and then click Import.

19. Click Next to move past the Welcome dialog box of the Certificate Import Wizard.

20. Enter the path and filename of the CA's .cer file.

21. Click Next.

22. Select Place all certificates in the following store, and then click Browse.

23. Select Show physical stores.

24. Expand Trusted Root Certification Authorities within the list, and then select Local Computer.

25. Click OK, click Next, and then click Finish.

26. Click OK to close the confirmation message box.

27. Refresh the view of the Certificates folder within the MMC snap-in and confirm that the CA's certificate is listed.

28. Close the MMC snap-in.

Step 6. Develop a Web Application to Call the Web Service

This procedure creates a simple ASP.NET Web application. You will use this ASP.NET Web application as the client application to call the Web service.

To create a simple ASP.NET Web application

1. On the Web service client computer, create a new C# ASP.NET Web application called SecureMathClient.

2. Add a Web reference (by using HTTPS) to the Web service.

   1. Right-click the References node within Solution Explorer, and then click Add Web Reference.

   2. In the Add Web Reference dialog box, enter the URL of your Web service. Make sure you use an HTTPS URL.

      Note   If you have already set a Web reference to a Web service without using HTTPS, you can manually edit the generated proxy class file and change the line of code that sets the Url property from an HTTP URL to an HTTPS URL.

   3. Click Add Reference.

3. Open WebForm1.aspx.cs and add the following using statement beneath the existing using statements.

   using SecureMathClient.WebReference1;
   

4. View WebForm1.aspx in Designer mode and create a form like the one illustrated in Figure 2 using the following IDs:

   • operand1
   • operand2
   • result
   • add

   

   Figure 2. WebForm1.aspx form

5. Double-click the Add button to create a button-click event hander.

6. Add the following code to the event handler.

   private void add_Click(object sender, System.EventArgs e)
   {
     math mathService = new math();
     int addResult = (int) mathService.Add( Int32.Parse(operand1.Text), 
                                         Int32.Parse(operand2.Text));
     result.Text = addResult.ToString();
   }
   

7. On the Build menu, click BuildSolution.

8. Run the application. Enter two numbers to add, and then click the Add button.

   The Web application will call the Web service using SSL.

Additional Resources

• How To: Set Up SSL on a Web Server
• How To: Call a Web Service Using Client Certificates from ASP.NET 1.1

© Microsoft Corporation. All rights reserved.