Writing a custom security handler

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

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. The message handler must also be able to cope with security on inbound and outbound messages.

Here is a likely set of steps that your security handler would implement:
  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:
    • 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.
    • To perform basic authentication of a password or password phrase, issue an EXEC CICS VERIFY PHRASE command. 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.
    • You might also want to write an audit record each time a service is requested, for example, you could write a message to a CICS® user journal.
    • To perform advanced authentication, either by exchanging or validating a range of tokens with a Security Token Service, use the Trust client interface which enables you to interact with the STS directly. . See Invoking the Trust client from a message handler for details.
    • Validate the credentials of the digital certificate if the message is signed.
    • If parts of the message are encrypted, decrypt the message using the information in the security header. The How CICS complies with Web Services Security specifications specification provides information about how to do this
  4. 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.

For examples of custom message handlers, see IBM Redbooks: Implementing CICS Web services.