White Mesa SOAP Server: SOAP Digest Authentication Implementation

The SOAP Digest Authentication Proposal offers a means to control access to SOAP services using a Digest Authentication scheme similar to that specified in RFC2617 . It is implemented as a SOAP extension, embodied in a collection of SOAP Header blocks.

The White Mesa Digest Authentication implementation consists of a Header processing NT service, a XML Schema document containing the schema and and a demonstration service definition.

The Header processor handling the Digest Authentication Header blocks may take advantage the ability of the White Mesa server to act as an intermediary. This is described in more detail here. The server's Header processing mechanism is discussed here , including the topic of WSDL syntax for describing SOAP Header blocks.

Configuration of the Digest Authentication Service is detailed below. The existing implementation offers only very simple user and security realm management.

A live node exists for demonstration purposes at http://www.whitemesa.net/interop/std/soapauthtest and browser based test clients are available to exercise the service:

• Test Client "A"
• Test Client "B"

The clients require IE 5.0 or higher to run. The wire dumps are displayed so that the Digest Authentication Header blocks can be examined in detail.

Configuration

Setting up Digest Authentication to control access to a SOAP service requires:

• Configuring the SOAP service to use the Digest Authentication Server as a Header processor. This requires adding the ProgID of the Server ("Wmsoapauthsvc.wmsoapauth") to the list of Header processors for the protected SOAP service. This step can be accomplished by using the White Mesa SOAP Server Control Panel or by modifying the service definition in the XML configuration file, as detailed here.
• Providing the supporting Header message definitions and binding information in the WSDL document used to define the service. The demonstration service WSDL document provides an example of these necessary elements.
• Configuring the Digest Authentication Server with the realm and user information associated with the protected service. This involves associating a security realm name with the protected service, as well as defining the users (and associated passwords) who are members of the realm. These steps are accomplished by editing the XML configuration file for the Digest Authentication Server, described below.

Example

Here is an example "echoString()" call from the client to endpoint "delta.whitemesa.net":

[Request from client to server]

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope 
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Header>
      <h:ClientAuth 
	  xmlns:h="http://soap-authentication.org/digest/2001/10/" 
	  SOAP-ENV:mustUnderstand="1">
         <Nonce>A5BBD2ED659494B5254752F3116B0262</Nonce>
         <Auth>3714D0B28FFBC6AB644152FC40BECB77</Auth>
         <UserID>guest</UserID>
         <Realm>testclients@whitemesa.net</Realm>
         <ClientNonce>C34982ACEE27BCB332E8E599462233BC</ClientNonce>
      </h:ClientAuth>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
      <m:echoString xmlns:m="http://soapinterop.org/">
         <inputString>Hello World!</inputString>
      </m:echoString>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

[Response from server to client]

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope 
	SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Header>
      <h:NextChallenge 
	SOAP-ENV:mustUnderstand="1" 
	xmlns:h="http://soap-authentication.org/digest/2001/10/">
         <Status>Authenticated</Status>
         <Nonce>F68D2245D7849FBC5FCAF0B68D43BB63</Nonce>
         <ClientNonce>C34982ACEE27BCB332E8E599462233BC</ClientNonce>
         <ServerAuth>B025B8D80A360A314E0709A37B81C1E8</ServerAuth>
      </h:NextChallenge>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
      <m:echoStringResponse xmlns:m="http://soapinterop.org/">
         <return>Hello World!</return>
      </m:echoStringResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The Digest Authentication Configuration File

This is found in the root installation directory along with the Digest Authentication server executable file wmsoapauthsvc.exeand is named auth-config.xml. The server will not function if this file is renamed or is not present in the same directory as the executable. It's a good idea to back it up regularly. Here is an example configuration file as it would appear immediately after installation. It can be divided into three sections:

• A global properties section.
• A "soapServices" element which maps services to security realms.
• An "authRealms" element in which security realms are defined.

Any text editor may be used to maintain the configuration file. Take care to observe proper XML syntax when making changes. Elements may simply be commented out in order to temporarily disable a property (e.g. a user account)without actually deleting it from the file.

Global properties:

The nonceLife element specifies the number of seconds that may elapse before a "server nonce" issued by the Authentication server as part of a "challenge" becomes stale. The defaultRealm element specifies the default security realm.

SOAP Services to Realm Mapping:

The "soapServices" element contains zero or more "service" elements. These elements associate a relative URI representing a defined service endpoint with the security realm under which it is protected. Each "service" element contains:

• A name element which specifies the service being protected. It is of type "anyURI" and is the same URI used to identify the service in the SOAP Server configuration file.
• A realm element which specifies the security realm. It is of type "string".

A service element is required for each SOAP service endpoint for which Digest Authentication is desired. It must reference a realm defined in the "authRealms" section described below.

Security Realms Definitions

The "authRealms" element contains zero or more "realm" elements. These are structured as follows:

• name element - this specifies the name of the realm. It is of type "string".
• users element - this specifies a list of zero or more user accounts. It consists of a sequence of "user" elements which are structured as follows:
  • userId element - this specifies the username (id) of the account. It is of type "string"
  • password element - this specifies the users password. It is of type "string".
  User accounts must have unique userId values within a particular realm.

Security realms are typically created to protect a class of applications that share the same user base. When client programs run, they often display the security realm name to the user as a hint for recall of the proper username/password combination required. The names of realms should therefore be suggestive of the application domain, e.g. "customer-service@example.com" offers the hint that the user needs to authenticate in their "customer service" role.