Writing a custom security handler

If you want to use your own security procedures and processing, you can write a custom message handler to process secure SOAP messages in the pipeline.

Before you begin

You need to decide the level of security that your security handler must support, and ensure that an appropriate SOAP fault is returned when a message includes security that is not supported.

About this task

The message handler must also be able to cope with security on inbound and outbound messages.

Procedure

  1. Retrieve the DFHREQUEST or DFHRESPONSE container using an EXEC CICS GET CONTAINER command.
  2. Parse the XML to find the security token that is in the WS-Security message header.
    The header starts with the <wsse:Security> element. The security token might be a user name and password, a digital certificate, or an encryption key. A message can have many tokens in the security header, so your handler needs to identify the correct one to process.
  3. Perform the appropriate processing, depending on the security that is implemented in the message.
    1. Start of changeIf you want to perform basic authentication of a Kerberos token, issue an EXEC CICS VERIFY TOKEN command.
      This command checks that the supplied Kerberos token is valid.
      If the command is successful, update the DFHWS-USERID container with an EXEC CICS PUT CONTAINER. Otherwise, issue an EXEC CICS SOAPFAULT CREATE command.
      End of change
    2. Start of changeIf you want to perform basic authentication of a password or password phrase, issue an EXEC CICS VERIFY PHRASE command.End of change
      This command checks the user name and password in the security header of the message.
      If the command is successful, update the DFHWS-USERID container with an EXEC CICS PUT CONTAINER. Otherwise, issue an EXEC CICS SOAPFAULT CREATE command.
    3. If you want to perform advanced authentication, either by exchanging or validating a range of tokens with a Security Token Service, use the Trust client interface.
      See Invoking the Trust client from a message handler for details.
    4. Validate the credentials of the digital certificate if the message is signed.
    5. If parts of the message are encrypted, decrypt the message using the information in the security header.
      The Web Services Security: SOAP Message Security specification provides information about how to do this.

Results

Define your security handler program in CICS® and update the pipeline configuration file, ensuring that it is correctly placed in the XML. In a service requester pipeline configuration file, the security handler must be configured to run at the end of the pipeline. In a service provider pipeline configuration file, the security handler must be configured to run at the beginning of the pipeline.

What to do next

For general information about how to write a custom message handler, see the IBM® Redbooks® publication Application Development for CICS Web Services that is available from http://www.redbooks.ibm.com/abstracts/sg247126.html.