Configuration Guides › Policy Server Configuration Guide › Authentication Schemes › XML Document Credential Collector Authentication › Configure the XML DCC Authentication Scheme › Configure Additional Mappings

Configure Additional Mappings

You can define any number of field-to-document mappings for the XML DCC authentication scheme in addition to the required "user" mapping used to map the user name field in the user store.

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 SOA Security Manager builds the XPath query for you as you select fields to map.
• Use the Advanced XPath query option to build more complex XPath queries manually.

To configure XML DCC field mappings

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

   Field mapping settings open.

2. Enter the name of a field from the user store, such as "email" in the Name field. This is 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:
   • Type an XPATH query defining the mapping in the XPath field.
   • Load a schema (.xsd) file and select the element to map to the specified field name by browsing using the following procedure:
     1. Unset the Advance XPath query option.
     2. Click Browse and navigate to a schema file in the File Upload dialog that appears.
     3. Click Upload XSD File.

        The schema is uploaded.

     4. 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. 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).

     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, navigate to 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 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.

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

Sometimes, the required credentials are in a SOAP body payload, but the XML is screened from the parser either by a CDATA section or by use of 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 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 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 this 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">
 <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>