Previous Topic: Authentication Scheme OverviewNext Topic: How to Configure XML DSIG Authentication to Verify User Identities Associated with X.509 Certificates


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.

Diagram showing the workflow for configuring an XML DCC authentication scheme

To configure CA SiteMinder WSS 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:

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:
  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:

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:
  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>