How it works: SOAP message security

Support for WS-Security, WS-Trust, and WS-Policy specifications

The Web Service Security (WS-Security) specification provides a foundational set of SOAP message extensions for building secure web services by defining elements to be used in the SOAP header for message-level security. It specifies the use of security tokens, digital signatures, and XML encryption to protect and authenticate SOAP messages. It specifies the use of digital signatures to provide integrity for XML elements in a SOAP message, and it specifies the use of encryption to provide confidentiality for XML elements in a SOAP message. The specification allows you to protect the body of the message or any XML elements within the body or the header. You can give different levels of protection to different elements within the SOAP message. For more information, see the Web Services Security: SOAP Message Security 1.0 specification.

The Web Services Trust Language (WS-Trust) specification extends WS-Security by providing a framework for requesting and issuing security tokens, and managing trust relationships between web service requesters and providers. This extension to the authentication of SOAP messages enables web services to validate and exchange security tokens of different types by using a trusted third party. This third party is called a Security Token Service (STS). For more information about WS-Trust, see the Web Services Trust Language specification.

CICS does not support WS-Policy. Security constraints can be specified by using WS-Policy within the WSDL but these specifications are ignored by CICS. CICS uses the pipeline configuration file to specify the security handler. For more information, see Configuring the pipeline for Web Services Security. CICS supports only the WS-Security 1.0 and WS-Trust 1.2 specifications.

What SOAP message security offers

Figure 1 shows how a SOAP message can be extended with security data that is used to authenticate the service requester and to protect the message as it passes between the requester and a CICS web service provider. You configure SOAP message security either by using a CICS security handler or by using the Trust client interface. The CICS security handler and the WS-Sec message header are both using WS-Security.

Components of SOAP message security

CICS security handler

To implement WS-Security in CICS for either a web service provider or a web service requester, you configure a security handler in the pipeline configuration file. CICS provides a security handler to cover the most common scenarios. For more information about using the CICS security handler, see Configuring the pipeline for Web Services Security.

To use your own security procedures and processing, you can write a custom security handler to process secure SOAP messages. For information about writing your own security handler, see Writing a custom security handler.

In addition to the CICS security handler, CICS provides a Trust client interface so that you can interact with a Security Token Service (STS) without using the CICS security handler. For information about using this interface, see Invoking the Trust client from a message handler.

Security Token Service (STS)

An STS is a web service that acts as a trusted third party to broker trust relationships between a web service requester and a web service provider, allowing web services from different trust domains to communicate successfully. Like a certificate authority in a TLS handshake, the STS guarantees that the service requester and the service provider can trust the credentials that are provided in the message. The trust is represented through the exchange of security tokens. An STS can issue, exchange, and validate these security tokens, and, in doing so, establish trust relationships between different trust domains.

The STS enables CICS to accept and send messages that have security tokens in the message header that are not directly supported by the CICS security handler; for example, LTPA and Kerberos tokens. CICS can be configured as a Security Token Service for SAML assertions. For information about using SAML assertions, see Configuring CICS for SAML.

CICS acts as a Trust client. The CICS security handler uses the information in the pipeline configuration file to send a web service request to the STS.

In a service provider pipeline, depending on how you configure the security handler, the request that is sent to the STS can be used for either of the two things:

• To validate a security token in the WS-Security message header of the inbound message.
• To exchange a security token in the WS-Security message header for a security token that CICS can understand.

In a service requester pipeline, the request can be only one thing: to exchange a security token for a different type of token. The pipeline configuration file defines what type of token the STS issues to the security handler.

The security handler dynamically creates a pipeline to send the web service requests to the STS. This pipeline exists until a response is received from the STS after which it is deleted. If the request is successful, the STS returns an identity token or the status of the validity of the token. The security handler places the RACF® ID that is derived from the token in the DFHWS-USERID container. If the STS encounters an error, it returns a SOAP fault to the security handler. The security handler then passes a fault back through the pipeline to the web service requester.

For more information about using an STS, see Configuring the pipeline for Web Services Security.

Trust client interface

The Trust client interface enables you to interact with a Security Token Service (STS) directly, rather than using the CICS security handler. Using an STS offers more advanced processing of tokens than the processing that the CICS security handler offers: for example, you can enable specific processing to handle many tokens in the inbound message headers or to exchange multiple types of token for outbound messages. Using this interface, you can create a custom message handler to send your own web service request to the STS.

You can use the Trust client interface without enabling the CICS security handler in your service provider and service requester pipelines, or you can use the Trust client interface in addition to the CICS security handler.

The Trust client interface is an enhancement to the CICS-supplied program DFHPIRT. This program is usually used to start a pipeline when a web service requester application is not deployed by using the CICS web services assistant. But it can also act as the Trust client interface to an STS.

You can invoke the Trust client interface by linking to DFHPIRT from a message handler or header processing program, passing a channel called DFHWSTC-V1 and a set of security containers, described in Security containers. Using these containers, you request either a validate or issue action from the STS, select which token type to exchange, and pass the appropriate token from the message header. DFHPIRT dynamically creates a pipeline, composes a web service request from the security containers, and sends it to the STS.

DFHPIRT waits for the response from the STS and passes this back in the DFHWS-RESTOKEN container to the message handler. If the STS encounters an error, it returns a SOAP fault. DFHPIRT puts the fault in the DFHWS-STSFAULT container and returns to the linking program in the pipeline.

For more information about interacting directly with an STS, see Invoking the Trust client from a message handler.