Configuring the pipeline for WS-Security

To configure a pipeline to support WS-Security, 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. Remember that CICS does not support WS-Policy and ignores any security constraints that you configure in the WSDL document.

For information about the elements of pipeline configuration files, see Support for WS-Security.

Procedure

  1. Add a <wsse_handler> element to your pipeline for a security handler.
    For information about the structure of this element, see <wsse_handler> pipeline configuration element. The security handler must be included in the <service_handler_list> element in a service provider or requester pipeline. The order of handler elements in the <service_handler_list> element determines the order that each handler is called at run time. In a pipeline that supports WS-Security, encrypted SOAP messages remain encrypted until the <wsse_handler> element is called. Therefore, you must specify the <wsse_handler> element before any other handler program that processes unencrypted messages.
    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.

  2. Optional: Code an <authentication> element.
    For information about the structure of this element, see The <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.
    2. Optional: If you specified trust=none, code the mode attribute to specify how credentials found in the message are processed.
    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.

  3. Optional: Code an <sts_authentication> element as an alternative to the <authentication> element.
    Do not code both in your pipeline configuration file. For information about the structure of this element, see The <sts_authentication> element. 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.
    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.
  4. 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 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 an IBM® 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.

    6.3 Support for SAML using the CICS Security Token Service is removed as of CICS TS 6.3.

  5. 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.

  6. Optional: If you want to reject inbound SOAP messages that are digitally signed, code an empty <reject_signature/> element.
  7. 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.

  8. If you want to reject inbound SOAP messages that are partially or fully encrypted, code an empty <reject_encryption/> element.
  9. 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>
  10. 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>