Invoking the Trust client from a message handler

CICS provides an interface so that you can write your own message handler to invoke a Security Token Service (STS). With this interface you can perform more advanced processing than the CICS-supplied security handler.

Before you begin

About this task

You can use the Trust client instead of the security handler or in addition to it. To use the Trust client interface:

Procedure

  1. Extract the correct token from the security message header of the inbound or outbound message.
  2. Link to program DFHPIRT, passing the channel DFHWSTC-V1 and the following required containers:
    • DFHWS-STSURI, containing the location of the STS on the network.
    • DFHWS-STSACTION, containing the URI of the type of request that the STS must perform. The two supported actions are issue and validate.
    • DFHWS-IDTOKEN, containing the token that must either be verified or exchanged by the STS.
    • DFHWS-TOKENTYPE, containing the type of token that the STS must send back in the response.
    • DFHWS-SERVICEURI, containing the URI of the web service operation that is being invoked.
    You can optionally include the DFHWS-XMLNS container to provide the namespaces of the SOAP message that contains the security token. This container is described in more detail in The header processing program interface.
  3. DFHPIRT returns with the response from the STS.
    A successful response is stored in the DFHWS-RESTOKEN container.

    If the STS encounters a problem with the request, it returns a SOAP fault. DFHPIRT puts the SOAP fault in the DFHWS-STSFAULT container. If the STS provides a reason for issuing the SOAP fault, the reason is put in the DFHWS-STSREASON container.

    If an abend occurs, a DFHERROR container is returned that contains details of the processing error.

    Your message handler must handle these responses and perform suitable processing in the event of an error. For example, the message handler might return a suitable SOAP fault to the web service requester.

  4. Process the response as appropriate.
    In provider mode, your pipeline processing must ensure that a user name that CICS can understand is placed in the DFHWS-USERID container by the time the message reaches the application handler. In requester mode, your message handler must add the correct token to the outbound message security header.

What to do next

When you have written your message handler, deploy the program in CICS and update the appropriate pipeline configuration files. In service requester pipelines, define your message handler to occur at the end of the pipeline processing but before the CICS-supplied security handler. In service provider pipelines, define your message handler at the beginning of the pipeline but after the CICS-supplied security handler.