Web Services Security Guides › CA SiteMinder® Web Services Security Policy Configuration Guide › Configure Authentication Schemes to Verify User Identities Obtained from Web Service Requests › How to Configure XML DCC Authentication to Verify User Identities Using Credentials Gathered from XML Request Messages

How to Configure XML DCC Authentication to Verify User Identities Using Credentials Gathered from XML Request Messages

Configure an XML Document Credential Collector (XML DCC) authentication scheme to validate user credentials obtained from incoming web service request documents.

To configure CA SiteMinder® Web Services Security to validate user identities using XML DCC authentication, complete the following process:

1. Configure the XML DCC authentication scheme.
2. Configure XML DCC field mappings.

Configure the XML DCC Authentication Scheme

To obtain authentication information from an incoming XML document, configure the XML DCC authentication scheme.

Follow these steps:

1. Click Infrastructure, Authentication.
2. Click Web Services Authentication Schemes, Create Authentication Scheme.

   The Create Authentication Scheme pane opens.

   Authentication scheme settings open.

3. Enter a name and a description for the scheme in the General group box.
4. Select XML Document Credential Collector from the Authentication Scheme Type list.
5. Specify a protection level.
6. Configure XML DCC field mappings in the Scheme Setup section.
7. (Optional) Select the Require Secure Transport Layer check box to require that authentication only take place over an SSL connection.

   Important! The Policy Server expects the information in the XML document to be in clear text. To enforce security, we recommend that you configure this authentication scheme over an SSL connection.

8. Click Submit.

   The authentication scheme is saved. You can now assign it in application object components or realms.

More information:

(Optional) Configure Other Field Mappings

Configure the Required "user" Mapping

How to Configure XML DCC Field Mappings

To create XML DCC mappings in the Administrative UI, map a user store field name to an XPath string that identifies an element of an XML document. Create these field mappings by browsing a specific XML schema file (.xsd or .dtd) or by entering an XPath query language string directly.

The XML DCC authentication scheme requires only one mapped field—"user"—to identify the XML document element that identifies the user to authenticate. To meet this requirement, the Field Mapping dialog forces the first field mapping that you create to be named "User". The only other specific field mapping name is "Password." To authenticate users by username and password, configure a second mapping named "Password."

To configure XML DCC field mappings, complete these procedures:

1. Configure the required "user" mapping
2. (Optional) Configure other field mappings

Configure the Required "user" Mapping

The required "user" mapping entry maps the user name field in the user store. The "user" mapping is created when you create an XML DCC authentication scheme. Before you configure any further mappings, map this value to a field in the XML document.

Two methods for creating mappings are as follows:

• Open a schema and select elements from it that you want to map to the user store. This method is easier because CA SiteMinder® Web Services Security builds the XPath query for you as you select fields for mappings.
• Use the Advanced XPath query option to build more complex XPath queries manually.

Follow these steps:

1. Locate the Scheme Setup section on the Create Authentication Scheme pane and click the Edit button beside the "user" field mapping entry.

   Field mapping settings open.

2. Do one of the following:
   • Type an XPATH query defining the mapping for "user" in the XPath field.
   • Load a schema (.xsd) file and select the element to map to "user" by browsing using the following procedure:
     1. Unset the Advance XPath query option.
     2. If the schema file you require is remote (for instance, if it is typically accessed over HTTP using its URL), download it to a local drive.
     3. Click Browse and navigate to a schema file in the File Upload dialog that appears.
     4. Click Upload XSD File.

        The schema is uploaded.

     5. Select the schema element that you want to map to the 'user" field name in the Select a node group box.

        The Select a node group box displays the selected schema using a standard tree-style hierarchical view. Click the plus sign (+) next to an element to expand it. Click the minus sign (-) beside an expanded element to contract it. Elements marked with an asterisk (*) are repeatable within the XML document (that is, incoming XML documents may contain multiple instances of that element).

3. (Optional) Specify the XPath function (count, div, index, mod, sum) that you want to apply to the mapping by choosing it from the Function drop-down list.

   The Function option lets you create more complex mappings by processing functions that further evaluate the XML document. For more information about these functions, navigate to the XPath specification at http://www.w3.org.

4. Specify whether the mapped information is located relative to the message body or message header by selecting the Message Body or Message Header option button.

   This defines the root of the XML document and tells XPath where to search for the relevant information. If the document has multiple headers, XPath uses the value of the first header that resolves.

5. Click OK to save your changes and return to the Create Authentication Scheme pane.

(Optional) Configure Other Field Mappings

Aside from the "user" mapping, you can define any number of other XML DCC field mappings.

Two methods for creating mappings are as follows:

• Open a schema and select elements from it that you want to map to the user store. This method is easier because CA SiteMinder® Web Services Security builds the XPath query for you as you select fields to map.
• To build more complex XPath queries manually, use the Advanced XPath query option.

Follow these steps:

1. Locate the Scheme Setup section on the Create Authentication Scheme pane and click Add.

   Field mapping settings open.

2. Enter the name of a field in the user store, such as "email" in the Name field. This specifies the name of the field to which you are mapping the XML element.

   Note: This name must match an entry in the user store; it is not case-sensitive.

3. Do one of the following tasks:
   • Type an XPATH query defining the mapping in the XPath field.
   • Load a schema (.xsd) file and browse to the element to map to the specified field name using the following procedure:
     1. Unset the Advance XPath query option.
     2. Click Browse.
     3. Navigate to a schema file in the File Upload dialog that appears.
     4. Click Upload XSD File.

        The schema is uploaded.

     5. Select the schema element that you want to map to the specified field name in the Select a node group box.

        The Select a node group box displays the selected schema using a standard tree-style hierarchical view. To expand an element, click the plus sign (+) next to it. To contract an element, click the minus sign (-) next to it. Elements marked with an asterisk (*) are repeatable within the XML document (that is, incoming XML documents can contain multiple instances of that element).

     Note: A loaded schema is not persistent; even when creating multiple mapping from the same schema file, you must reload the schema for each mapping.

4. (Optional) Specify the XPath function (count, div, index, mod, sum) that you want to apply to the mapping by choosing it from the Function drop-down list.

   The Function option lets you create more complex mappings by processing functions that further evaluate the XML document. For more information about these functions, see the XPath specification at http://www.w3.org.

5. Specify whether the mapped information is located relative to the message body or message header by selecting the Message Body or Message Header option button.

   This setting defines the root of the XML document and tells XPath where to search for the relevant information. If the document has multiple headers, XPath uses the value of the first resolved header.

6. Click OK to save your changes and return to the Create Authentication Scheme pane.

XML DCC XPath Mapping Examples

The following examples show XPath expressions to perform complex mappings.

Example Namespace-aware XPath Query

In the following XML file, the username and password are in the SOAP body, and the first element below the body is prefixed by a namespace. It would not therefore be possible to obtain these elements using the schema browsing method.

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <env:Header>
  </env:Header>
  <env:Body>
    <n1:sayHello testnum="purchaseOrder11c" xmlns:n1="http://www.xyz.com/examples/Trader">
      <BillingInformation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\data\CredentialHeader.xsd">
	<CustomerCredentials>
		<username>Robm</username>
		<password>password</password>
		<PIN>String</PIN>
	</CustomerCredentials>
      </BillingInformation>
    </n1:sayHello>
  </env:Body>
</env:Envelope>

To obtain the username, specify the following XPath query:

/*[local-name()='sayHello' and namespace-uri()='http://www.xyz.com/examples/Trader']/BillingInformation/CustomerCredentials/username

To obtain the password, specify the following XPath query:

/*[local-name()='sayHello' and namespace-uri()='http://www.xyz.com/examples/Trader']/BillingInformation/CustomerCredentials/password

Example XPath Query to Obtain Credentials From Embedded XML Documents

Required credentials can be present in a SOAP body payload, but the XML screened from the parser by a CDATA section or by replacement of angle brackets by entity references.

The following XPath queries will work for either CDATA or entity-reference screened XML.

XPath query for username

The following XPath query can be used to obtain a username mapping from the CDATA section or from entity-reference screened XML:

	substring-before(substring-after(/*[local-name()='sayHello' and namespace-uri()='http://www.bea.com/examples/Trader']/text(),'<username>'),'</username>')

XPath query for password

The following XPath query can be used to obtain a password mapping from the CDATA section or from entity-reference screened XML:

	substring-before(substring-after(/*[local-name()='sayHello' and namespace-uri()='http://www.bea.com/examples/Trader']/text(),'<password>'),'</password>')

Sample document containing credentials in CDATA section

The following sample XML document shows username and password credentials that are screened by a CDATA section.

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<env:Header>
<BillingInformation>
	<CustomerCredentials>
		<username>Robm</username>
		<password>password</password>
	</CustomerCredentials>
</BillingInformation>
</env:Header>
<env:Body>
<n1:sayHello testnum="purchOrder05-cdata" xmlns:n1="http://www.bea.com/examples/Trader">

<![CDATA[<!--Sample XML file generated by XMLSpy v2005 rel. 3 U (http://www.altova.com)-->

<BillingInformation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\data\CredentialHeader.xsd">

	<CustomerCredentials>
		<username>Robm</username>
		<password>password</password>
		<PIN>String</PIN>
	</CustomerCredentials>

</BillingInformation>
]]>
</n1:sayHello>
</env:Body>
</env:Envelope>

Sample document containing credentials in entity-referenced screened XML

The following sample XML document shows username and password credentials that are screened by the use of replacement of angle brackets by entity references.

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<env:Header>
<BillingInformation>
	<CustomerCredentials>
		<username>Robm</username>
		<password>password</password>
	</CustomerCredentials>
</BillingInformation>
</env:Header>
<env:Body>
<n1:sayHello testnum="purchaseOrder04" xmlns:n1="http://www.bea.com/examples/Trader">

&lt;!--Sample XML file generated by XMLSpy v2005 rel. 3 U (http://www.altova.com)--&gt;

&lt;BillingInformation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\data\CredentialHeader.xsd"&gt;

	&lt;CustomerCredentials&gt;
		&lt;username&gt;Robm&lt;/username&gt;
		&lt;password&gt;password&lt;/password&gt;
		&lt;PIN&gt;String&lt;/PIN&gt;
	&lt;/CustomerCredentials&gt;
&lt;/BillingInformation&gt;

</n1:sayHello>
</env:Body>
</env:Envelope>

Example XPath Query to Obtain Credentials with a Default Namespace for all Elements

In the following XML file, the sayHello element has a default namespace specified by xmlns="http://www.xyz.com/examples/Trader".

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <env:Header>
  </env:Header>
  <env:Body>
    <sayHello testnum="purchaseOrder11c" xmlns="http://www.xyz.com/examples/Trader">
      <BillingInformation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\data\CredentialHeader.xsd">
	<CustomerCredentials>
		<username>Robm</username>
		<password>password</password>
		<PIN>String</PIN>
	</CustomerCredentials>
      </BillingInformation>
    </sayHello>
  </env:Body>
</env:Envelope>

This following XPath query searches for the element "username" with the namespace "http://www.xyz.com/examples/Trader" anywhere in the document:

/*[local-name()='username' and namespace-uri()='http://www.xyz.com/examples/Trader']

Example XPath Query that Explicitly Specifies the Namespace Prefix

To extract the username and password (without namespace prefix) from a SOAP message, you can use an XPath query with an explicit tag including the namespace prefix and colon (:) as a simple text string.

For example, you could use the following XPath query to extract the username and password (without namespace prefix) from the sample SOAP message.

Example XPath query with explicit tag

This XPath query could be used to extract the username and password (without namespace prefix) from the sample SOAP message that follows.

//*[name()='wsu:dccuser']
//*[name()='wsu:dccpwd']

Sample SOAP message

The preceding XPath query could be used to extract the username and password (without namespace prefix) from this sample SOAP message.

<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" 
  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
 <soap:Header>
   <wsa:Action>http://example.com/services/XMLProcess_WebReq_portWebReq/Operation_1</wsa:Action> 
   <wsa:MessageID>urn:uuid:e0b940b0-7d44-4e1e-b391-2e65c5b1de3f</wsa:MessageID> 
   <wsa:ReplyTo>
    <wsa:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:Address> 
   </wsa:ReplyTo>
   <wsa:To>http://ex01/XMLProcess_Proxy/XMLProcess_WebReq_portWebReq.asmx</wsa:To> 
   <wsse:Security>
    <wsu:Timestamp wsu:Id="Timestamp-cedeb96e-9b12-45e6-bdf1-6e6c323a24cb">
     <wsu:Created>2006-04-12T18:31:33Z</wsu:Created> 
     <wsu:Expires>2006-04-12T18:36:33Z</wsu:Expires> 
     <wsu:dccuser>catest1</wsu:dccuser> 
     <wsu:dccpwd>msimsi</wsu:dccpwd> 
    </wsu:Timestamp>
   </wsse:Security>
 </soap:Header>
 <soap:Body>
   <Operation_1 xmlns="http://example.com/services">
    <XMLClaim MemberID="123456789" SubscriberID="987654321" TimeStamp="20060412 13:31:32:952" TranNumber="270" ControlID="1" xmlns="http://Example.Claim_XML" /> 
   </Operation_1>
 </soap:Body>
</soap:Envelope>

Example XPath Query With Namespace and Element-by-Element Navigation

Use the following XPath query, with namespace and element-by-element navigation:

/*[local-name()='Security' and namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'][1]/*[local-name()='Timestamp' and namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'][1]/*[local-name()='dccuser' and namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'][1]

/*[local-name()='Security' and namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'][1]/*[local-name()='Timestamp' and namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'][1]/*[local-name()='dccpwd' and namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'][1]

/*[local-name()='Security' and 

namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'][1]

/*[local-name()='Timestamp' and 

namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'][1]

/*[local-name()='dccuser' and 

namespace-uri()='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'][1]

To extract the username and password from the following SOAP message:

<soap:Envelope 
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" 
  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
 
   <wsa:Action>http://example.com/services/XMLProcess_WebReq_portWebReq/Operation_1</wsa:Action> 
   <wsa:MessageID>urn:uuid:e0b940b0-7d44-4e1e-b391-2e65c5b1de3f</wsa:MessageID> 
   <wsa:ReplyTo>
    <wsa:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:Address> 
   </wsa:ReplyTo>
   <wsa:To>http://ex01/XMLProcess_Proxy/XMLProcess_WebReq_portWebReq.asmx</wsa:To> 
   <wsse:Security>
    <wsu:Timestamp wsu:Id="Timestamp-cedeb96e-9b12-45e6-bdf1-6e6c323a24cb">
     <wsu:Created>2006-04-12T18:31:33Z</wsu:Created> 
     <wsu:Expires>2006-04-12T18:36:33Z</wsu:Expires> 
     <wsu:dccuser>catest1</wsu:dccuser> 
     <wsu:dccpwd>msimsi</wsu:dccpwd> 
    </wsu:Timestamp>
   </wsse:Security>
 </soap:Header>
<soap:Body>
   <Operation_1 xmlns="http://example.com/services">
    <XMLClaim MemberID="123456789" SubscriberID="987654321" TimeStamp="20060412 13:31:32:952" TranNumber="270" ControlID="1" xmlns="http://Example.Claim_XML" /> 
   </Operation_1>
 </soap:Body>
</soap:Envelope>