Configuring the pipeline for Web Services Security

To configure a pipeline to support Web Services Security (WSS), you must add a security handler to your pipeline configuration files. You can use the security handler supplied with CICS, as described, or create your own.

Before you begin

Before you define the CICS-supplied security handler, you must identify or create the pipeline configuration files to which you add configuration information for WSS.

Procedure

Add a <wsse_handler> element to your pipeline.
The handler must be included in the <service_handler_list> element in a service provider or requester pipeline.
Code the following elements:
```
<wsse_handler>
  <dfhwsse_configuration version="1">

  </dfhwsse_configuration>
</wsse_handler> 
```
The <dfhwsse_configuration> element is a container for the other elements in the configuration.
Optional: Code an <authentication> element.
- In a service requester pipeline, the <authentication> element specifies the type of authentication that must be used in the security header of outbound SOAP messages.
- In a service provider pipeline, the element specifies whether CICS uses the security tokens in an inbound SOAP message to determine the user ID under which work is processed.
1. Code the trust attribute to specify whether asserted identity is used and the nature of the trust relationship between service provider and requester.
  For details of the trust attribute, see The <authentication> element.
2. Optional: If you specified trust=none, code the mode attribute to specify how credentials found in the message are processed.
  For details of the mode attribute, see The <authentication> element.
3. In the <authentication> element, code these elements:
  1. An optional, empty <suppress/> element.
    If this element is specified in a service provider pipeline, the handler does not attempt to use any security tokens in the message to determine under which user ID the work runs.
    
    If this element is specified in a service requester pipeline, the handler does not attempt to add to the outbound SOAP message any of the security tokens that are required for authentication.
  2. In a requester pipeline, an optional <algorithm> element that specifies the URI of the algorithm that is used to sign the body of the SOAP message. You must specify this element if the combination of trust and mode attribute values indicate that the messages are signed. You can specify only the RSA with SHA1 algorithm in this element. The URI is http://www.w3.org/2000/09/xmldsig#rsa-sha1.
  3. An optional <certificate_label> element that specifies the label that is associated with an X.509 digital certificate installed in RACF®. If you specify this element in a service requester pipeline and the <suppress> element is not specified, the certificate is added to the security header in the SOAP message. If you do not specify a <certificate_label> element, CICS® uses the default certificate in the RACF key ring.
    This element is ignored in a service provider pipeline.
Optional: Code an <sts_authentication> element as an alternative to the <authentication> element.
You must not code both in your pipeline configuration file. This element specifies that a Security Token Service (STS) is used for authentication and determines the type of request that is sent.
1. Optional: In service provider mode only, code the action attribute to specify whether the STS verifies or exchanges a security token.
  For details of the action attribute, see The <sts_authentication> element.
2. Within the <sts_authentication> element, code these elements:
  1. An <auth_token_type> element. This element is required when you specify a <sts_authentication> element in a service requester pipeline and is optional in a service provider pipeline. For more information, see The <auth_token_type> element.
    - In a service requester pipeline, the <auth_token_type> element indicates the type of token that STS issues when CICS sends it the user ID contained in the DFHWS-USERID container. The token that CICS receives from the STS is placed in the header of the outbound message.
    - In a service provider pipeline, the <auth_token_type> element is used to determine the identity token that CICS takes from the message header and sends to the STS to exchange or validate. CICS uses the first identity token of the specified type in the message header. If you do not specify this element, CICS uses the first identity token that it finds in the message header. CICS does not consider the following as identity tokens:
      
      wsu:Timestamp
      
      xenc:ReferenceList
      
      xenc:EncryptedKey
      
      ds:Signature
  2. In a service provider pipeline only, an optional, empty <suppress/> element. If this element is specified, the handler does not attempt to use any security tokens in the message to determine the user ID that the work runs under. The <suppress/> element includes the identity token that is returned by the STS.
Optional: Code an <sts_endpoint> element.
Use this element only if you have also specified an <sts_authentication> element. In the <sts_endpoint> element, code the following elements:
- An <endpoint> element. This element contains a URI that points to the location of the Security Token Service (STS) on the network. It is recommended that you use SSL or TLS to keep the connection to the STS secure, rather than using HTTP.
  To use SAML support, set the endpoint to cics://PROGRAM/DFHSAML.
  
  You can also specify a WebSphere® MQ endpoint, by using the JMS format of URI.
- An optional <jvmserver> element. This element identifies the JVM server that is configured to run the SAML token service. If this element is not included, the default sample resource JVM server DFHXSTS is assumed. This element is valid only if you are using SAML: if you use it in other situations, an error occurs.
Optional: If you require inbound SOAP messages to be digitally signed, code an empty <expect_signed_body/> element.
The <expect_signed_body/> element indicates that the <body> of the inbound message must be signed. If the body of an inbound message is not correctly signed, CICS rejects the message with a security fault.
Optional: If you want to reject inbound SOAP messages that are digitally signed, code an empty <reject_signature/> element.
Optional: If you require inbound SOAP messages to be encrypted, code an empty <expect_encrypted_body/> element.
The <expect_encrypted_body/> element indicates that the <body> of the inbound message must be encrypted. If the body of an inbound message is not correctly encrypted, CICS rejects the message with a security fault.
If you want to reject inbound SOAP messages that are partially or fully encrypted, code an empty <reject_encryption/> element.
Optional: If you require outbound SOAP messages to be signed, code a <sign_body> element.
1. In the <sign_body> element, code an <algorithm> element.
2. Following the <algorithm> element, code a <certificate_label> element.
Here is an example of a completed <sign_body> element:
```
<sign_body>
  <algorithm>http://www.w3.org/2000/09/xmldsig#rsa-sha1</algorithm>
  <certificate_label>SIGCERT01</certificate_label>
</sign_body>
```
Optional: If you require outbound SOAP messages to be encrypted, code an <encrypt_body> element.
1. In the <encrypt_body> element, code an <algorithm> element.
2. Following the <algorithm> element, code a <certificate_label> element.
Here is an example of a completed <encrypt_body> element:
```
<encrypt_body>
  <algorithm>http://www.w3.org/2001/04/xmlenc#tripledes-cbc</algorithm>
  <certificate_label>ENCCERT02</certificate_label>
</encrypt_body>
```

Example

The following example shows a completed security handler in which most of the optional elements are present:

<wsse_handler>
    <dfhwsse_configuration version="1">
      <authentication trust="signature" mode="basic">
        <suppress/>
        <certificate_label>AUTHCERT03</certificate_label>
      </authentication>
      <expect_signed_body/>
      <expect_encrypted_body/>
      <sign_body>
        <algorithm>http://www.w3.org/2000/09/xmldsig#rsa-sha1</algorithm>
        <certificate_label>SIGCERT01</certificate_label>
      </sign_body> 
      <encrypt_body> 
        <algorithm>http://www.w3.org/2001/04/xmlenc#tripledes-cbc</algorithm>
        <certificate_label>ENCCERT02</certificate_label>
      </encrypt_body>		
    </dfhwsse_configuration>
</wsse_handler>