Building Secure Web Services with Microsoft SOAP Toolkit 2.0

  • Article

 

Kirill Gavrylyuk
Test Lead, Web Data SOAP Team
Microsoft Corporation

July 2001

Summary: Microsoft SOAP Toolkit 2.0 provides a flexible framework to build scalable Web services for various intranet and Internet solutions. Security is an important aspect of building reliable services in both scenarios. SOAP Toolkit 2.0 provides support for Internet security based on the Microsoft IIS security infrastructure. This article describes how to build secure solutions with the Microsoft SOAP Toolkit 2.0. (23 printed pages)

January 2005 Update: SOAP Toolkit 2.0 is no longer supported. Information in this article may apply to SOAP Toolkit 3.0, which has been deprecated by the Microsoft .NET Framework. See the SOAP Toolkit page on the MSDN Web Services Developer Center for information on available support for SOAP Toolkit 3.0.

Contents

Introduction
Golden Rules
Authentication
Proxy Support and Authentication
SSL and Client Certificates
Authorization Caveats
Troubleshooting
For More Information

Introduction

As with any distributed protocol, a critical part of any successful SOAP application is getting the security right. The SOAP standard doesn't specify any security mechanisms; it delegates security handling to the transport layer. For the SOAP Toolkit 2.0, that transport layer is HTTP. SOAP running on HTTP is basically just a Web application like any other ASP or ISAPI application that you have running on Microsoft IIS. Authentication, authorization, and encryption for SOAP use the same mechanisms as your favorite Web applications do. If you are familiar with Web security, you already know SOAP security. If you haven't worked much with Web applications, this paper will give you enough background to get started. Each topic is covered at a fairly high level. If you want more detail, check out the book, Designing Secure Web-Based Applications for Microsoft Windows 2000 by Michael Howard, Marc Levy, and Richard Waymire.

Golden Rules

Based on the ideas laid out in Designing Secure Web-Based Applications for Microsoft Windows 2000, we will start by outlining the golden rules in building secure Web services. The following seven standards make up a secure Web service:

  • Authentication
  • Authorization
  • Auditing
  • Privacy
  • Integrity
  • Availability
  • Nonrepudation

Authentication is a process by which an entity, also called a principal, verifies that another entity is indeed who or what it claims to be. The SOAP Toolkit 2.0 provides support for the following authentication methods:

  • Basic
  • Digest
  • Kerberos
  • Windows NTLM
  • SSL and Client certificates
  • SOAP headers-based
  • Proxy

In this document we will explain how to configure both the server- and client-sides to use these methods.

Authorization is a mechanism to provide an authenticated user with access to resources. As long as Web services built with the SOAP Toolkit are based on IIS, they can leverage authorization mechanisms supported by IIS. In this document we will cover some issues that user should be aware of.

The purpose of auditing is to collect information about successful and failed requests to a Web service. You can use the auditing features of IIS and the tracing feature of SOAP Toolkit for this purpose. This isn't covered here, but you can refer to IIS documentation, netmon logging and SOAP Toolkit Help for the SoapServer object.

Privacy means ensuring that information provided in a communication between client and server is hidden from an attacker. Integrity refers to the ability to protect data from being deleted or changed, either maliciously or by accident. For Privacy and Integrity purposes, SOAP Toolkit allows you to use Secure Socket Layer (SSL) for data encryption. In this document we will describe how to enable SSL support on IIS and how to use it on the client.

Availability is ensuring that a legitimate user is not denied access to a requested resource. Examples of availability technology include load-balancing and failover hardware and software. The SOAP Toolkit was successfully tested with Microsoft Application Center load balancing software.

Nonrepudation is a technique for providing proof that an action occurred so as to prevent the client from fraudulently reneging on a transaction. The SOAP Toolkit leverages nonrepudation features provided by IIS. Nonrepudation is not covered by this document.

Authentication

Authentication methods supported by the SOAP Toolkit are covered in this section, including their benefits and drawbacks and how to set them up. Also covered are the known limitations of the SOAP Toolkit on supported platforms, and the SOAP Toolkit HTTP connector behavior in case several authentication schemes are available from the server.

What happens during an authentication handshake? Each authentication handshake starts with the following:

  1. The client sends a request to the page.
  2. The server returns status 401 Access Denied and a set of HTTP headers WWW-Authenticate for each authentication methods it supports.

How do you use SoapClient to authenticate yourself? If your Web service requires authentication (Basic, Digest, NTLM or Kerberos), you need to provide a user name and password to SoapClient so it can pass them to the Web service. You can do this using SoapClient.ConnectorProperty bag:

dim SoapClient
set SoapClient = createobject("MSSoap.SoapClient")
SoapClient.mssoapinit("https://your-server/webservice/service.wsdl ")
SoapClient.ConnectorProperty("AuthName") = "username"
SoapClient.ConnectorProperty("AuthPassword") = "userpwd"
Quote = SoapClient.GetQuote()

Note   With SOAP Toolkit 2.0, you must set ConnectorProperties on SoapClient only before any remote method is called.

If a virtual directory where the wsdl file with the service description is located also requires authentication, you can pass the user name and password inside the URL:

SoapClient.mssoapinit("https:// username:userpwd@your-server
   /webservice/service.wsdl ")

There is an incorrect belief that putting the user name and password in the URL is a less secure method. This is not correct. Before sending the HTTP request, client HTTP code will parse the URL, remove user name and password and will use them in the authentication handshake. In fact, the code:

SoapClient.ConnectorProperty("AuthName") = "username"
SoapClient.ConnectorProperty("AuthPassword") = "userpwd"
Quote = SoapClient.GetQuote()

is equivalent to the following code, provided that WSDL file service.wsdl points to itself:

SoapClient.ConnectorProperty("EndPointURL")= "https:// 
username:userpwd@your-server/webservice/service.wsdl"
Quote = SoapClient.GetQuote()

How is a virtual directory set up to require authentication? To change authentication settings on the server for a specific virtual directory:

  1. On both IIS 4.0 and IIS 5.0, right-click the virtual directory, click Properties, and then click the Directory Security tab.
  2. Under Anonymous Access and Authentication, click Edit. You will have the following options:

Anonymous Access

Anonymous access is not an authentication method. Microsoft® Windows® 2000 and Microsoft Windows NT® 4.0 require users to authenticate themselves before accessing any resource, so IIS uses a special account for an anonymous Web user (by default IUSR_machinename) in this case. You can change the default anonymous Web user account or its password by clickin the Anonymous Access Edit button.

Note   Be careful not to use privileged accounts for anonymous Web user accounts. To set up the virtual directory to require authentication, you need to clear the Anonymous Access flag.

Basic Authentication

To set up a virtual directory to require Basic Authentication:

  1. On the Properties menu, click Directory Security, click Edit Anonymous Access and then click Authentication.
  2. Clear the Anonymous Access check box.
  3. Enable Basic Authentication. You will see a warning message. Click OK if you want to continue to use Basic Authentication.
  4. Click the Basic Authentication Edit button. Type or select the domain name from the list. Type \ if you want to use the default domain name.

Drawbacks: Basic authentication is very insecure. The user name and password are sent Base64-encoded over the wire without encryption. The problem is not only that an attacker can get to a resource secured by Basic authentication, but also that the attacker can get the actual values of your user name and password and can use them to access other more secure resources. But if you use an SSL connection, it becomes secure because the SSL handshake happens before the authentication handshake. Therefore the user name and password are passed over a secure connection.

Benefits: Basic authentication is a part of the HTTP 1.0 protocol and is the most widely supported authentication scheme.

Conclusion: Basic authentication is a good bet if and only if coupled with SSL. Use this method if you want your service to be secure and highly interoperable.

Digest Authentication

This relatively new method, begun with Microsoft Windows 2000, is part of HTTP1.1 protocol, but is not commonly spread among Web servers. To set up Digest authentication on IIS 5.0:

  1. On the Properties menu, click Directory Security, click Edit Anonymous Access, and then click Authentication.
  2. Clear the Anonymous Access check box.
  3. Enable Digest Authentication. You will see a warning message. Click OK if you want to continue to use Digest Authentication.

Using Digest authentication requires:

  • The Windows 2000 Server system is in an Active Directory domain.
  • A file named iissuba.dll is installed on the domain controller. This DLL performs work during anonymous access and Digest authentication.
  • All accounts logging on using Digest Authentication are configured with the Store Password Using Reversible Encryption option enabled in the Active Directory settings. This is needed to give Digest Authentication access to a clear text copy of the account's password in Active Directory. Doing this ensures that the server where these passwords are stored is very secure.

Drawbacks: Digest authentication does not secure resources from replay attack if not coupled with SSL. It is not yet widely used among other HTTP client and server implementations. Its implementation on IIS 5.0 has a limitation such that if you logged in to the server through Digest authentication, identity cannot be delegated to another server. This limits server-to-server scenarios.

Benefits: Digest authentication is simple and might be more popular. It is more secure than Basic authentication: though replay attack is still feasible, an attacker cannot get actual values of the user name and password required to access other resources.

Conclusion: Digest authentication can be used to secure low-value resources exposed through a Web service to the Internet. You get much better performance using Basic over SSL, since SSL is slow, but it does not expose user names and passwords to attackers like Basic Authentication.

Windows Integrated Authentication (NTLM)

Windows Integrated authentication (Windows Challenge/Response authentication in IIS 4) stands for different methods on Windows 2000 and NT 4. Under NT 4 with IIS 4, it was described as NTLM authentication. To set up your IIS server to require Windows Integrated Authentication (on IIS 5) or NTLM (on IIS 4), complete the Basic or Digest authentication steps 1 and 2 in the above sections, and select the corresponding check box in step 3.

NTLM authentication (NT LAN Manager or Windows Challenge/Response authentication) is the native Windows authentication scheme. If user name/password are not specified, the current logon user credentials are used. With access over an intranet, if the user is already logged to the same domain as the Web server the user does not have to authenticate again if using their logon credentials. During NTLM handshake the client hashes the password with random values sent by the server (challenge) and then sends this hash (response) to the server. This means that no passwords are sent explicitly over the wire. It is a common misconception that NTLM is only for intranet solutions and should not be used over the Internet; NTLM can be used for the Internet, but with the intranet it is much faster, as it relies on the Windows logon procedure. To pass the domain name with the login name, use the SAM account name:

SoapClient.ConnectorProperty("AuthName") = "DOMAIN\username"

Drawback: NTLM is restricted to Windows. As with Basic and Digest authentication schemes, it authenticates only the client. When NTLM is used, the impersonated thread on the server cannot delegate its privilege to another server. This limits use of NTLM authentication in server-to-server scenarios; you can still use it with Basic and Digest. NTLM doesn't work through proxies.

Benefits: NTLM is more secure than Basic and Digest because it is not feasible to break in with a replay attack. It is fast in intranet scenarios since it relies on the Windows logon procedure.

Conclusion: NTLM is recommended for use in client-to-server intranet solutions. It can be used in corporate Internet solutions that are restricted to the Windows architecture.

Kerberos Authentication

Kerberos authentication appeared in Windows 2000. When you specify IIS 5 to use Windows Integrated Authentication, IIS 5 and the SoapClient HTTP connector use the Negotiate protocol to determine whether NTLM or Kerberos is to be used. If the SoapClient is running on Windows 2000, Kerberos will be used; otherwise NTLM will be used. The same rules apply for specifying user credentials on SoapClient, as in the case of NTLM.

Drawbacks: Kerberos is supported only on the Windows 2000 platform. Kerberos requires a KDC server to request a service ticket from. You normally don't want to expose your KDC server on the Internet, so Kerberos is normally restricted to intranet applications. By default, only the NetBIOS name of the server is registered in the Kerberos KDC. If you want to use the DNS name of your IIS server when requesting a ticket, the DNS name has to be registered in the KDC.

Benefits: Compared to NTLM, Kerberos is faster, more secure, and authenticates both server and client. Kerberos is not a Windows proprietary authentication scheme; it is implemented by other platforms as well. An important point is that it allows delegation of identity to another computer so it can be used in server-to-server scenarios.

Conclusion: Kerberos is recommended for use with Windows 2000-based intranet solutions.

Sometimes you need to support several authentication schemes on your server (to allow several types of clients to authenticate). In this case, IIS will send several WWW-Authenticate headers detailing the authentication schemes it supports and the Client will choose the first authentication scheme among those that it supports. It is important to know which authentication scheme will be chosen by the SoapClient under particular circumstances. Refer to Table 1, which describes the behavior of SOAP Toolkit 2.0 (more precisely, HttpConnector) on different platforms.

Table 1. SOAP Toolkit 2.0 HttpConnector vs. IIS 5.0

Basic Digest Windows integrated Windows 98 Windows Me Windows NT 4.0 Windows 2000
X X   Basic Basic Basic Digest
X   X NTLM NTLM NTLM Kerberos
  X X NTLM NTLM NTLM Kerberos
X X X NTLM NTLM NTLM Kerberos

The left three columns stand for authentication schemes offered by the server. Each row represents a different combination of allowed authentication schemes set on the server. The four right columns show platforms that the SOAP Toolkit Client (HttpConnector) could be running on. For example: If the server allows both Basic and Digest authentication, SOAP will choose Basic on all platforms except for Windows 2000.

Table 2 shows the Microsoft SOAP behavior compared to the IIS 4.0 server.

Table 2. SOAP Toolkit 2.0 HttpConnector vs. IIS 4.0

Basic Windows integrated Windows 98 Windows Me Winodws NT 4.0 Windows 2000
X X NTLM NTLM NTLM NTLM

Known limitations in authentication support: The SOAP Toolkit 2.0 limitation of being unable to send the domain name along with account name using NTLM/Kerberos is fixed in the SP2 release.

Proxy Support and Authentication

The SOAP Toolkit provides extensive support for communication through proxy servers including authentication on the proxy server. We will walk through the following scenarios to describe how to work with Web services through proxy servers.

Direct Access

By default, the SOAP Toolkit HttpConnector tries to perform a direct call to a Web service. If you don't have direct access to the Web service (the Web service is outside of your intranet and you must go through a proxy, for example), the following script will fail:

dim SoapClient
set SoapClient = createobject("MSSoap.SoapClient")
SoapClient.mssoapinit("https://services.xmethods.net/soap/urn:xmethods-
   CurrencyExchange.wsdl")
Quote = SoapClient.GetQuote()

Access Through Default Proxy

When you try to access a Web site outside of your intranet, the Microsoft Internet Explorer Web browser goes through default proxy server specified in the IE settings. You can look at these settings by referring to the IE/Tools/Options/Connections/LAN settings dialog. To make the Microsoft SOAP Toolkit (HTTPConnecter) use these settings, you should set the UseProxy property to TRUE. Example:

dim SoapClient
set SoapClient = createobject("MSSoap.SoapClient")
SoapClient.mssoapinit("https://services.xmethods.net/soap/urn:xmethods-
   CurrencyExchange.wsdl")
SoapClient.ConnectorProperty("UseProxy") = true
Quote = SoapClient.GetQuote()

Bypass proxy list. Note that in the IE proxy settings, there is a list of hosts that you connect to in order to bypass the proxy server.

  1. In Internet Explorer, on the Tools menu, click Options, click Connections, and then click LAN Settings.
  2. In the LAN Settings dialog box, to bypass local servers, enable ByPass proxy servers for local addresses.
  3. To bypass the proxy when connecting to other specific servers, click Advanced. You can list servers you want to bypass in the Exceptions edit control, separating each name with a semicolon. You can use wild cards like "*.soap-company.com" to bypass all servers having .soap-company.com in their names.

You need the proxy server to allow for bypass of any server that is outside its local intranet. Note that you can have different proxies for HTTP and for connections through SSL (HTTPS). Your proxy should allow either protocol to be used in order for SSL to work.

Limitations: There is a known issue with the Microsoft SOAP Toolkit 2.0 HttpConnector on Windows 2000 and Windows NT 4.0 when using the Default proxy. HttpConnector does not understand the ByPass Proxy list from default IE proxy settings. It bypasses the proxy if ByPass proxy servers for local addresses is turned on and the host name specified in URL doesn't contain a ".". But it doesn't understand the complicated templates that you can put into the Exceptions text box in the IE Proxy Settings Advance menu.

Connect Through Specific Proxy

You can specify which proxy to use with the ProxyServer and ProxyPort connector properties:

set SoapClient = createobject("MSSoap.SoapClient")
SoapClient.mssoapinit("https://services.xmethods.net/soap/urn:xmethods-
   CurrencyExchange.wsdl")
SoapClient.ConnectorProperty("UseProxy") = true
SoapClient.ConnectorProperty("ProxyServer") = "yourproxy"
SoapClient.ConnectorProperty("ProxyPort") = 80
Quote = SoapClient.GetQuote()

Note that you don't have to set UseProxy to TRUE if you use the ProxyServer property; it will be set automatically.

Proxy Authentication

A proxy server may require you to authenticate yourself before the connection goes through. For example, it may be used to restrict use of the Internet from within a corporate intranet. Proxy servers may use all authentication schemes discussed above. Microsoft SOAP Toolkit 2.0 allows you to specify a user name and password for proxy authentication:

set SoapClient = createobject("MSSoap.SoapClient")
SoapClient.ConnectorProperty("UseProxy") = true
SoapClient.mssoapinit("https://services.xmethods.net/soap/urn:xmethods-
   CurrencyExchange.wsdl")
SoapClient.ConnectorProperty("ProxyServer") = "secureproxy"
SoapClient.ConnectorProperty("ProxyPort") = 80
SoapClient.ConnectorProperty("ProxyUser") = "username"
SoapClient.ConnectorProperty("ProxyPassword") = "password"
Quote = SoapClient.GetQuote()

If your Proxy requires NTLM authentication, you may omit user name and password, causing it to use the current logon credentials. If you need to specify a domain name for proxy NTLM authentication, add "DOMAIN\username" as for server authentication.

Limitations. Microsoft SOAP Toolkit 2.0 does not support connection to a server that requires authentication through a proxy that also requires authentication. Additionally, SSL connections through a proxy that requires authentication will not work on Windows 2000 and Windows NT 4.0.

SSL and Client Certificates

In this section we will walk through the process of enabling connections through Secure Socket Layer (SSL) and client certificates support. We will also cover known limitations of Microsoft SOAP Toolkit 2.0 on supported platforms using client certificate support.

It is common to think about SSL only as an encryption mechanism, but it also provides authentication. To enable IIS 4.0/IIS 5.0 to support SSL connections, you need to get and install the X.509 certificate on the server.

What Are X.509 Certificates?

A certificate is a structure that contains information about its subject, issuer name, validity period and other characteristics. (For more information about certificates, see Designing Secure Web-Based Applications for Microsoft Windows 2000 by Michael Howard et al.) Each certificate is related to a pair of private and public keys used in SSL encryption. SSL always uses X.509 certificates to authenticate a Web server.

To get a certificate, you need to make a certificate request to a Certificate Authority. A Certificate Authority (CA) is a unit that issues certificates. When a CA issues a certificate to the subject (the entity that made request), it verifies that the subject is who it claims to be and signs the new certificate with its private key. Thus the subject can delegate the trust to the CA. If you trust the CA that issued the certificate, you will trust the subject that presented this certificate to you. The root certificate guarantees the trustworthiness of the CA. CAs can form chains: If you trust the root CA, you trust an intermediary CA that has a certificate issued by the root CA, and therefore you trust all subjects of certificates that were issued by an intermediary CA.

What does "trust" physically mean? You trust a CA by putting its certificates into the Trusted Root Certification Authorities store. All certificates are stored in so called certificate stores. There are several default stores, for example:

CURRENT_USER\MY\Personal certificates store for current logged-in user, not visible if other users log in

LOCAL_MACHINE\MY\Personal certificates store common for all users

CURRENT_USER\Root\Trusted Root Certification Authorities and contains certificates for user-trusted root CAs. Certificates with a certification path to a root CA certificate are trusted by the current user for all valid purposes of the certificate.

LOCAL_MACHINE\Root\Same, but trusted by all users

There are root CAs that are trusted by default, such as Verisign. Though our examples use a trial Verisign certificate, these are issued by the Verisign Test Authority, which is not trusted by default.

Enabling SSL on the Server

This section explains how to create a certificate request, get a trial server-side certificate from the Verisign site, and install it on your Web server.

To enable SSL on the server using IIS 4.0

  1. Right-click the Web site that you want to SSL-enable and select Properties.

  2. On the Directory Security tab, click Edit Secure Communications.

  3. In the dialog box, click Key Manager.

  4. In the tree-view, expand the Local Computer node. Right-click the WWW leaf, and select Create new key. This starts the certificate request wizard called Key Manager.

    Select Put request in a file that you will send to authority and a file name. Click Next.

    Enter a key name that is easy to remember. Enter a password, which you will need when you will get certificate issued from authority. For encryption key byte length, select 1024 (1024 is recommended; some authorities do not issue certificates with smaller key lengths). Click Next.

    Enter your organization and unit name. Enter a Common Name that is equivalent to your full site name, e.g. www.yoursite.com. Before starting an SSL connection, clients will check if the site has the same name as the Common Name of its certificate. Click Next.

    Enter Country region, State/Province, City Locality. The Certificate Authority may check if this information is consistent, so be sure to enter valid information. When entering the state, enter the full state name.

    Enter the name of the person who administrates the server, e-mail address, and phone number. This info will not be in the certificate, but the Certificate Authority needs it.

  5. A file with your request has been created. It is Base64-encoded. During this process, IIS also creates a private and public key for this certificate request. The private key will stay on your computer, whereas the public key will go to Verisign along with the request and will be used to encrypt the certificate data.

  6. Go to www.verisign.com and click Get Trial SSL ID. While enrolling for the certificate, you will be asked for CSR (Certificate Signing Request). Copy and paste the content of your request file starting with the line, "BEGIN NEW CERTIFICATE REQUEST;" otherwise, you will get an error. Verisign will mail you the test server-side certificate back. The same procedure applies for commercial certificates, with one difference: you will be asked for money and the information you submit will be carefully verified.

  7. Make sure that the certificate you get from the Certification Authority is Base64-encoded. With Verisign you might get it in e-mail. Create an empty file with a ".cer" extension and copy and paste all content between the lines "BEGIN CERTIFICATE" and "END CERTIFICATE" (inclusive) into it.

  8. Go to the Properties/Directory Security tab of the site you are trying to SSL-enable. Click Edit Secure Communications and then click Key Manager.

  9. In the dialog box, expand the Local Computer node in the tree-view and expand the WWW leaf. You will see the key for your certificate request as the leaf. It is marked red since the certificate is not yet installed. Right-click it and select Install Key certificate. Select the file with the certificate to install. You will be prompted for the password you established earlier. Enter the password. Your certificate is now installed.

To enable SSL on the server using IIS 5.0

  1. Right-click the Web site that you want to SSL-enable and select Properties.

  2. On the Directory Security tab, click Edit Secure Communications.

  3. Click Server Certificate to open the Server Certificate Wizard. This wizard remembers the current state of the Web site, e.g. whether you have server certificate already or not. (We assume that you don't have it now.)

  4. In the Certificate Wizard, click Next, select Create A New Certificate, and then click Next.

    Select Prepare the request now but send it later and click Next.

    Enter the friendly name for the certificate. This name will not be used in the certificate structure, but as a way to distinguish requests and certificates. Select the public key length. It is recommended that you use at least a 1024 byte key length. Click Next.

    Enter your organization and a unit name that can be verified by an authority. Enter valid names if you are requesting a real certificate for commercial use. Enter the name of the computer to be certified. Note: It must be equal to your full site name, e.g. www.yoursite.com. Click Next.

    Enter Country/Region, State/Province, City/Locality. Certificate Authority may check if the information is consistent; please enter valid information. When entering the state, enter the full state name. Click Next.

    Enter request file name for the request to be saved in. Click Next.

    A summary of what you entered will be displayed. Verify that is correct and click Next to finish the wizard. A file with the request will be saved in Base 64 format.

  5. A file with your request has been created. It is Base64-encoded. During this process, IIS also creates a private and public key for this certificate request. The private key will stay on your computer, whereas the public key will go to Verisign along with the request and will be used to encrypt the certificate data.

  6. Go to www.verisign.com and click Get Trial SSL ID. During certificate enrollment, you will be asked for CSR (Certificate Signing Request). Copy and paste the contents of your request file starting with the line, "BEGIN NEW CERTIFICATE REQUEST;" otherwise, you'll get an error. Verisign will mail you the test server-side certificate back. The same procedure applies for commercial certificates, with one difference: you will be asked for money and the information you submitted will be carefully verified.

  7. Make sure that the certificate you get from the Certification Authority is Base64-encoded. With Verisign you might get it in e-mail. Create an empty file with a ".cer" extension and copy and paste all content between the lines "BEGIN CERTIFICATE" and "END CERTIFICATE" (inclusive) into it.

  8. Go to the Properties/Directory Security tab of the site you are trying to SSL-enable. Click Edit Secure Communications and then click Server Certificate. The Server Certificate Wizard knows that you just filed a request, so it expects you to have your certificate issued and ready to install it in IIS 5.0.

  9. Select Process the pending request and install the certificate and click Next. Select the file name for the certificate you got from the Certificate Authority. Click Next. Look at the certificate overview and click Next. Click Finish. Your Web server certificate is installed in IIS 5.0.

Configuring the Client for an SSL Connection

Having a properly configured server is not enough to enable a successful SSL connection. Remember that an SSL connection always includes the authentication step, where the client authenticates the server. In particular, the client verifies that the server has a valid certificate, e.g. the certificate is not out of date, not revoked, and is issued by a Certificate Authority that the client trusts. In the steps detailed above, we received a trial Verisign server-side certificate that was issued by the Verisign Test Root Authority. This authority is not trusted by default, e.g. its certificate is not in the Root store of your machine by default. Follow the instructions from Verisign site on how to get a Verisign Test Root Authority certificate. Once you get the file with the Verisign Test Root Authority certificate, you need to install it on all clients that you want to use SSL connections to your server (to trust server-side certificates when authenticating the server). Follow these steps:

  1. Double-click the file with certificate to open the certificate browser window.
  2. Click Install Certificate. On the Certificate Import Wizard Welcome page, click Next.
  3. Choose the store that you want to put this certificate into.

By default, Windows may put this certificate into CURRENT_USER\Root\store. This means that the computer will be able to trust certificates issued by this authority only under your account. To make sure that this will work for other users too, we recommend you always put root CA certificates into LOCAL_MACHINE\Root store. To do this:

  1. Select Place All Certificates in the Following Store and click Browse.

  2. Select Show Physical Stores, expand the Trusted Root Certification Authorities node, select Local Computer, and then select the "LOCAL_MACHINE\Root" store.

    Finish the wizard to install the CA Root Certificate.

Performing an SSL Connection

Try to open the SSL connection to your Web server. To do this, you must set up the Calc/Service/Rpc/AspVbsVb SOAP Toolkit Sample:

  1. On the server, perform all instructions for samples setup from the SOAP Toolkit 2.0 samples description file C:\Program Files\MSSOAP\Samples\default.html.

  2. On the server, edit C:\ProgramFiles\MSSOAP\Samples\Calc\Service\Rpc\AspVbsVb\calc.wsdl file and specify your Web server name in place of MSSOAP in the location URL:

    <port name='CalcSoapPort' binding='wsdlns:CalcSoapBinding' >
<soap:address location='https://your-server/MSSoapSamples/Calc
                               /Service/Rpc/AspVbsVb/Calc.asp' />
</port>

  3. On the client, run the following VBScript:

    Set Calc = CreateObject("MSSOAP.SoapClient")
Calc.mssoapinit https://your-server/MSSoapSamples/Calc/Service/Rpc/
     AspVbsVb/Calc.wsdl
Answer = Calc.add(14,28)
WScript.Echo "14+28=" & Answer

You have just made a connection through SSL. Note that if you change the URLs back to HTTP, you will be making a regular non-secure HTTP connection. To make your server require an SSL connection for your Web service, you need to set SSL required on the virtual directory your service is located in.

On IIS 4.0

  1. Right-click the virtual directory in IIS manager and choose Properties.
  2. On the Directory Security tab, click Edit Secure Communications.
  3. Enable Require secure channel when accessing this resource.

On IIS 5.0

  1. Right-click the virtual directory in IIS manager and choose Properties.
  2. On the Directory Security tab, click Edit Secure Communications.
  3. Enable Require SSL.

Now if you try to make a non-secure HTTP connection to this service, you will get an error.

Server Authentication in SSL

A common mistake is to use localhost or other aliases for the server host name in an SSL connection. During an SSL handshake, the client verifies that the Common Name (CN) part of the Subject name of the server certificate matches the host name found in the HTTP request. If it doesn't, the SSL connection will fail. The client also verifies that the server-side certificate is valid, not revoked, and issued by a trusted CA.

Client Certificates Authentication

Along with obligatory server authentication, SSL has an optional step: authenticating the client. This is done with the use of client certificates. Client certificates are similar to server certificates. A client sends client certificates to the server if the server is configured to require them. The server will at least check if it trusts this client certificate, e.g. if it was issued by a trusted Certificate Authority.

Configuring Client Certificate Authentication on the Server

Both IIS 4.0 and IIS 5.0 can be configured to:

  • Ignore client certificates. In this case, client certificates authentication is turned off.
  • Accept but not require client certificates. The client will be authenticated if a client certificate was provided. Authentication in this situation means only checking if the client certificate is valid and trusted.
  • Require client certificate. The connection will be rejected if a client certificate is not provided. The client certificate will be checked as in the previous option.
  • Require client certificate and map it to a specified user account. This means the same authentication as requiring the client certificate, but the IIS working thread will also impersonate the credentials of the specified user.

When you use client certificates issued by CAs other that the default trusted authority (such as Verisign or Thawte), you need to make sure that this CA root certificate is stored on the server in LOCAL_MACHINE\Root\store, and not in CURRENT_USER\Root\store. By default, the wizard puts the CA certificate into CURRENT_USER\Root\, which makes it invisible to IIS, since it uses a different user account.

How do you configure IIS to use one of the options listed above for client certificates? Follow the same steps in the above procedures, but in the third step do the following (dialogs are similar in IIS 4.0 and IIS 5.0):

  • To ignore client certificates, select Ignore client certificates on IIS 5.0 or Do not accept client certificates on IIS 4.0;
  • To accept but not require client certificates, select Accept client certificates;
  • To require a client certificate, select Require client certificates;
  • To require client certificates to match to a specified user account, select Require client certificates and select Enable client certificates mapping. For this you need to have a file with the exported client certificate that you want to map. To get it, on the client machine where you have the client certificate, do the following:

    1. In Internet Explorer, on the Tools menu, click Internet Options, click the Content tab, and then click Certificates.

    2. On the dialog that appears, you will have certificates stores: CURRENT_USER\MY, CURRENT_USER\Root, etc. (Note that you don't see any store from LOCAL_MACHINE\.)

    3. Select the certificate you want to export and click Export. In the wizard, select No, do not export private key and Base64-encoded X.509(.CER) format. Choose the file name. The result is a file with your client certificate exported.

    4. To add the file to the server, in the Edit client certificate mapping dialog box, click Add and select the file with your client certificate.

      You will be asked for a mapping name. Choose any name for the account name to map to the certificate and password. Every time a client gives this certificate when connecting to the service in this virtual directory, the request processing thread will be impersonated with the account you chose. For more information on using client certificates for authentication, please see the Step-by-Step Guide to Mapping Certificates to User Accounts on the Windows 2000 Web site.

Using SSL Client Certificates on the Client

This section covers what to do on the client when you need to provide a client certificate in order to talk to the service. How do you get and install a client-side certificate? You can get your client certificate (Web identity) from Verisign or from any other CA.

**Note   **Server certificates and client certificates have different purposes. You cannot use a server-side certificate as a client certificate.

Once you get the file containing the certificate (.cer file), double-click it to install it. Follow the same steps as before when you installed the Verisign Test CA root certificate. You will be asked which store you want to put your certificate into. The default (recommended) store for client certificates is CURRENT_USER\MY\.

Note When you prepare your request for the client certificate, you are usually asked whether or not you want to use the CURRENT_USER or LOCAL_MACHINE store for your certificate.

  • Use the CURRENT_USER store if you want your certificate to be accessible only from the account you are using to create the request.
  • Use the LOCAL_MACHINE store if you want several strong accounts to share access to this certificate. Only local admin accounts have access to the LOCAL_MACHINE store. For example, you might want to use this if you use SOAP over SSL with client certificate authentication for remote configuration purposes, and you want your client script to be useable from any local administrator's account.

Here are simple scripts to create requests for a client certificate and to install the certificate into the store of your choice. Scripts use the Certificates Enrollment control and are similar to scripts used for server certificates above:

CERT_SYSTEM_STORE_LOCAL_MACHINE= 131072 
OID_CLIENT_AUTH  = "1.3.6.1.5.5.7.3.2"
REQUEST_FILENAME = "ClientCertReq.txt"  
bUseLM = true
set enroll = CreateObject("CEnroll.CEnroll.1")
'Build the Distingueshed Name of certificate
strDN =  "CN=your-server,OU=UserUnit,O=UserOrg,L=UserCity,S=WA,C=US"
if bUseLM then
' if we want request and certificate to be in the LOCAL_MACHINE store
     enroll.MyStoreFlags      = CERT_SYSTEM_STORE_LOCAL_MACHINE
   enroll.RequestStoreFlags = CERT_SYSTEM_STORE_LOCAL_MACHINE
end if
'Otherwise by default request and certificate will be put to 
' CURRENT_USER store
'create request, specify usage of certificate(Client Authentication)
strReq = Enroll.createPKCS10( strDN, OID_CLIENT_AUTH)
'add BEGIN/END tags
strReq = "-----BEGIN NEW CERTIFICATE REQUEST-----" & vbCRLF & _
       strReq & _
       "-----END NEW CERTIFICATE REQUEST-------"
set fso = CreateObject("Scripting.FileSystemObject")
set f = fso.OpenTextFile(REQUEST_FILENAME, 2, true)
call f.Write(strReq)
f.Close()

The ClientCertReq.txt file will contain a Base64-encoded PKCS10 request. To install the SSL client certificate after you receive it from CA, use the following script:

FILE_CERTIFICATE = "certnew.cer"
CERT_SYSTEM_STORE_LOCAL_MACHINE= 131072 
bUseLM = true
set enroll = CreateObject("CEnroll.CEnroll.1")
if bUseLM then
'if we want request and certificate to be in the LOCAL_MACHINE store
enroll.MyStoreFlags= CERT_SYSTEM_STORE_LOCAL_MACHINE
enroll.RequestStoreFlags= CERT_SYSTEM_STORE_LOCAL_MACHINE
end if
'Otherwise by default Cenroll will use CURRENT_USER store. 
'You should specify the same store you used for request
enroll.acceptFilePKCS7(FILE_CERTIFICATE)

The script will take a certificate from the specified file and install it to the LOCAL_MACHINE store where IIS keeps server certificates. You can use these scripts for your configuration's automation.

How do you make SoapClient use a client certificate? This is fairly easy. You need to know which store your certificate is kept in and the certificate Common Name (CN part of subject name). The Common Name is displayed in the "Issued to" column when browsing certificates from IE5 or from the Microsoft Management Console (mmc.exe). The following script:

Set Calc = CreateObject("MSSOAP.SoapClient")
Calc.mssoapinit https://your-server/MSSoapSamples/Calc/Service/Rpc/AspVbsVb/Calc.wsdl
SoapClient.ConnectorProperty("SSLClientCertificateName") = "MyCert"
Answer = Calc.add(14,28)
WScript.Echo "14+28=" & Answer

takes a certificate with CN=MyCert from CURRENT_USER\MY store and makes a request to a secure service using this certificate. You can alternatively specify explicitly the store you want to use:

SoapClient.ConnectorProperty("SSLClientCertificateName") = "LOCAL_MACHINE\MY\MyCert"

The name of the certificate is case insensitive, but name of the store is case sensitive.

Client Certificates in Server-to-Server Scenario

We include a high level description and a sample secure B2B solution using client certificates. It is important to use client certificates correctly in server-to-server scenarios in order to keep them safe from an attacker.

Scenario: An Internet shop is using a third-party paid Web service to verify submitted client information, such as credit card numbers. The paid Web service requires client certificate authentication.

The Internet shop application requires the following components:

  • Web Application: A set of ASP pages that run in a High Protection (Isolated) Web Application (this is important). When they need to use Credit Card Number Verification Service, they call to COM+ application that does the job. These ASP pages do not access the client certificate and do not use SoapClient directly. The application allows anonymous access.
  • COM+ Application: Configured to run in a separate process under identity of specific local account. The client certificate used to authenticate to the third party Credit Card Number Verification Service is stored in this local account's personal (CURRENT_USER\MY\) store. This COM+ object is a proxy for the Credit Card Number Verification Service and it uses SoapClient to access this service and to authenticate using client certificate as described above.
  • Credit Card Number Verification Service: Requires SSL connection and Client Certificate authentication.

Client certificates are stored in a certificate store that cannot be accessed from any account that ASP pages can impersonate. In this way we ensure that an attacker cannot use the client certificate by executing script code, even if they get update access to the ASP pages. Do not access client certificates directly from ASP pages.

Known Limitations of SSL and Client Certificates Support

  1. Windows 98: Client certificates are not supported with some WinInet versions on Windows 98.
  2. Windows 98, Windows Me and Windows XP: If the virtual directory (on IIS 4.0 or IIS 5.0) containing your service is configured to require client certificates, then you can not connect to any other URL on this host that require client certificates. This is due to a certificates caching problem in WinInet and applies to the whole process lifetime. However, you can connect to the secure URL on another host.
  3. An SSL connection may hang upon close in Windows ME. See the Knowledge Base article Q238934 for more information. Contact Microsoft Product Support Services for QFE for this Windows ME issue.
  4. SoapClient on Windows 2000 and Windows NT4 can perform SSL connections only through port 443.

Authorization Caveats

Here we will talk on some authorization caveats you may run into while exposing COM objects using SOAP Toolkit 2.0. These are not security holes but you may want to avoid them in deploying secure Web services and ensure resources availability.

Accessing Files and Other Resources Under Anonymous Login

When you make a SOAP request to a Web service that allows anonymous login, IIS impersonates the request processing server thread with a special IUSR_machinename account. If the COM object you have exposed as Web service tries to use resources that forbid access for the IUSR_machinename account, you will get an "Access denied" error. To avoid this you can either change the privileges for the IUSR_machinename on this resource, or change the virtual directory setting to use a different account for anonymous access. (See the Authentication section)

Server-to-Server Scenario

Server-to-server is a very popular scenario, where the SoapClient object is used from inside an ASP file. For better performance you will want to cache the SoapClient object inside the global.asa file. This avoids having to call SoapClient.mssoapinit and parse WSDL file again. In this solution, if you are accessing another secure server that requires authentication, you need to set credentials in the global.asa: file.

In case of NTLM authentication you won't be able to do it due to delegation limitation (see the Authentication section).

Note   In the case of Kerberos, be sure to specify which credentials you want to use explicitly. DO NOT rely on current thread credentials, because the client with stronger credentials sends the first request, then all successive calls will reuse this connection. You could possibly open a security hole in your solution.

Note To make your solution more secure, we recommend that you put in separate COM+ application code that uses SoapClient and performs an authenticated connection. Look at the high-level description of the server-to-server solution using the Client certificate authentication proposed above. This way you will keep the User and password name from an attacker that gets access to the ASP pages source.

Note   If you decided to use SoapClient in an ASP page, we recommend running the ASP page in High Protection (Isolated) mode. Due to optimization, the SoapClient code that performs the HTTP connection runs under the process account and not under the calling thread's account. This means the HTTP code will be running under the system account if you use SoapClient in an ASP page that runs Low Protection (In Process) mode. If you use Isolated mode, it will run under IWAM_machinename account, which is safer.

Objects Running in MTS on NT 4.0:

Exposing a COM object that runs in an MTS Server Package on NT 4.0 may present problems relating to security. In NT 4.0, COM always uses the process identity when making a local COM call. This means that when the SOAP listener creates and calls your COM object, the call will be made using the process identity, and the fact that the processing thread is impersonating the user's credentials will be ignored. The MTS package will always see the incoming call as being made by the same user account. The user account will be the IWAM account (if the virtual directory where the SOAP listener resides is configured to run out of process) or the SYSTEM account (if the virtual directory where the SOAP listener resides is configured to run in process). Two implications result from this behavior:

  1. Since the impersonated user is ignored and calls are made using the process identity, MTS Role security is not very effective in this situation.
  2. It is not possible to identify the impersonated user from the MTS COM object. For example, calling GetDirectCallerName will not return the impersonated user, but will return IWAM or SYSTEM.

For more information, see the Knowledge Base Article #Q243437, PRB: Identity Different in MTS and COM+ Library Package by Default.

Troubleshooting

In this section, we want to go through typical problems you may run into when designing a secure Web application with the Microsoft SOAP Toolkit 2.0, and how to resolve them based on the information we provided in the previous section.

Getting Access Denied

You can get an "access denied" error when calling a server-side object exposed through SOAP. You can not get this error when calling an object locally and not through SOAP. Most likely you have your service running under the anonymous account and access resources (the file system or something else) that are not accessible from the IIS anonymous account. You need to change permissions on this resource, or forbid anonymous logon for this Web service. See the Authentication section for more information.

Basic Authentication Doesn't Work

Make sure you configured your virtual directory where your service is running to require Basic authentication and that you specified the domain name in the Basic authentication settings (use \ for default). See the Basic Authentication section.

Digest Authentication Doesn't Work

Read the requirements listed in the Digest Authentication section and verify that you didn't miss anything. Think twice about whether you really need to use Digest authentication.

Windows Integrated Authentication Doesn't Work

Check if your client is in the same domain as the server. If not, specify domain name with user name as shown in the example in the Windows Integrated Authentication (NTLM) section. If it doesn't work in the server-to-server scenario, make sure you have Windows 2000 on both ends. If you have Windows NT 4.0, then you are using NTLM, which is not applicable to server-to-server scenarios.

SOAP Toolkit Doesn't Work Through Proxy

Check if you set the UseProxy property and if you specify proxy server name correctly or you have it set in default Internet Explorer settings in case you use these. SOAP Toolkit 2.0 was tested for proxy support with many proxies available on the market (including Microsoft Proxy 2.0, ISA proxy, Apache proxy server, Netscape proxy server, etc.). Problems have been found only with the Netscape proxy.

SSL Doesn't Work

This is the most common problem. A server that is not correctly configured to support SSL usually causes errors. Please refer to the instructions in the SSL section. To check and see if the server is SSL-enabled, you can use Internet Explorer to access your service URL.

It is possible that the server-side certificate is not trusted on the client. On the client, make sure that you have installed a root certificate for the CA that issued the server-side certificate.

If you are running a server-to-server scenario, e.g. trying to use SoapClient in an ASP page to call to another server, make sure the installed root certificate for CA that issued the server-side certificate is installed into LOCAL_MACHINE store. For more details, refer to the SSL section.

SSL Client Certificates Do Not Work

Make sure that you specified the correct name and store of the client certificate in the SSLClientCertificateName connector property. You should specify the Common Name (CN) part of certificate's Subject name. To check the CN name for the certificate in CURRENT_USER\MY store, go to the Internet Explorer/Tools/Options/Content/Certificates menu and check the "Issued to" column in the list of available client certificates.

Make sure your client certificate is valid, e.g. if you go to the Internet Explorer/Tools/Options/Content/Certificates menu and click on you certificate, it doesn't show any warnings and displays that the "certificate is OK" and "you have a private key for the certificate."

Make sure that the server trusts your client certificate, e.g. the root certificate of the CA that issued your client certificate, and is in the LOCAL_MACHINE\Root store on the server. For details on how to check this, refer to the SSL and Client Certificates section.

Make sure process is running under an account that has access to the certificate store you specified. See notes in the server-to-server paragraph of the Authorization Caveats section.

For More Information

Designing Secure Web-Based Applications for Microsoft Windows 2000 by Michael Howard, Marc Levy, and Richard Waymire.

Running Microsoft Internet Information Server by Leon Braginski and Matt Powell.

Knowledge Base Article #Q243437, PRB: Identity Different in MTS and COM+ Library Package by Default.