Configuring provider mode web services for identity propagation

Identity propagation with a web service request relies on trust-based configurations; for example, using a client-certified SSL connection from WebSphere® DataPower®. In this task, you configure a PIPELINE resource to expect an ICRX identity token in the WS-Security header, sent from a trusted client.

Before you begin

You must configure your RACF RACMAP settings before you configure your web service connections, otherwise you receive the RACF ICH408I message for every unmapped request that is sent to RACF. For more information about configuring the RACF RACMAP command, see Configuring RACF for identity propagation.

You must configure a trust relationship between the WebSphere DataPower appliance and CICS, for example, using SSL client certification between WebSphere DataPower and CICS. The digital certificate that WebSphere DataPower uses to identify itself must be associated with a user ID, and that user ID must be granted surrogate authority to assert identities. For more information about surrogate authority, see Surrogate user security.

About this task

This task explains how to use CICS with a WebSphere DataPower appliance to provide a web service configuration that can propagate distributed identities in a secure and robust way. The circle in the diagram indicates that this task explains the CICS-specific configuration.
Figure 1. Configuring CICS to expect an ICRX identity token from WebSphere DataPower.
The diagram shows a DataPower appliance connecting to CICS using SOAP or HTTP, passing an distinguished name and realm, which are mapped to a distributed identity.

WebSphere DataPower acts as an intermediary between CICS and other applications. Remote web service requester applications connect to the WebSphere DataPower appliance using the SOAP protocol. WebSphere DataPower authenticates the credentials supplied by the remote client and mapping the credentials to a z/OS ICRX identity token, which identifies the distributed identity of a user. The SOAP message is then forwarded to CICS over the trusted SSL connection with an ICRX identity token in a WS-Security header. For more information about ICRX identity tokens, see z/OS Security Server RACF Data Areas.

CICS receives the SOAP message from WebSphere DataPower. The PIPELINE configuration file specifies blind trust, because the only possible client is the WebSphere DataPower appliance, and WebSphere DataPower is communicating with CICS over a secure SSL connection. Therefore, you do not need to specify additional authentication in the PIPELINE configuration file. The WS-Security handler program locates the first ICRX found in the WS-Security header and uses the ICRX to identify the user.

Procedure

  1. Create a PIPELINE resource, or edit an existing PIPELINE resource to specify the basic-ICRX mode, which allows the PIPELINE to receive an ICRX.
    The most typical combination is the blind trust with the basic-ICRX mode. For more information about the PIPELINE resource element, see The <authentication> element.
    Here is an example PIPELINE configuration file, showing blind trust with the basic-ICRX mode: 
    
<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<provider_pipeline xmlns="https://www.ibm.com//software/htp/cics/pipeline">
   <service>
     <service_handler_list>
       <wsse_handler>
         <dfhwsse_configuration version="1">
           <authentication trust="blind" mode="basic-ICRX"/>
         </dfhwsse_configuration>
       </wsse_handler>
     </service_handler_list>
     <terminal_handler>
       <cics_soap_1.2_handler/>
     </terminal_handler>
   </service>
   <apphandler>DFHPITP</apphandler>
</provider_pipeline>
    Here is an example SOAP message with an ICRX identity, using blind trust:
    <?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope 
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header>
    <wsse:Security 
        xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
        SOAP-ENV:mustUnderstand="1">

      <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss
-soap-message-security-1.0#Base64Binary"
        wsu:Id="ICRX"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd"
        ValueType="https://www.ibm.com//xmlns/prod/zos/saf#ICRXV1">

        ICRX IS HERE

      </wsse:BinarySecurityToken>

    </wsse:Security>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>

   APPLICATION SPECIFIC XML IS HERE

  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
  2. Ensure that WebSphere DataPower is configured to be able to send ICRX information. See Sample network topologies for using identity propagation.

Results

Web service requests from WebSphere DataPower with an ICRX identity token in the WS-Security header, connected over a client-certified SSL connection, can now flow.