Options for securing SOAP messages

You can choose from these options:

Trusted authentication

In service provider pipelines, CICS can accept a username token in the SOAP message header as trusted. This type of security token typically contains a user name and password, but in this case the password is not required. CICS trusts the provided user name and places it in container DFHWS-USERID, and the message is processed in the pipeline.

In service requester pipelines, CICS can send a username token without the password in the SOAP message header to the service provider.

Basic authentication

In service provider mode, CICS can accept a username token in the SOAP message header for authentication on inbound SOAP messages. This type of security token contains a user name and password. CICS verifies the username token using an external security manager, such as RACF. If successful, the user name is placed in container DFHWS-USERID and the SOAP message is processed in the pipeline. If CICS cannot verify the username token, a SOAP fault message is returned to the service requester.

Username tokens that contain passwords are not supported in service requester mode or on outbound SOAP messages.

HTTP basic authentication

In service provider mode, CICS can accept basic authentication information over an HTTP protocol. The service requester uses a URIMAP definition to specify that credentials (user identification information) can be captured by the global user exit, XWBAUTH. XWBAUTH passes this information to CICS on request and CICS sends the information in an HTTP authorization header to the service provider.

Advanced authentication

In service provider and requester pipelines, you can verify or exchange security tokens with a Security Token Service (STS) for authentication purposes. This authentication enables CICS to accept and send messages that have security tokens in the message header that are not normally supported; for example, Kerberos tokens or SAML assertions.

For an inbound message, you can select to verify or exchange a security token. If the request is to exchange the security token, CICS must receive a username token back from the STS. For an outbound message, you can exchange a username token only for a security token.

Signing with X.509 certificates

In service provider and service requester mode, you can provide an X.509 certificate in the SOAP message header to sign the body of the SOAP message for authentication. This type of security token is known as a binary security token. To accept binary security tokens from inbound SOAP messages, the public key associated with the certificate must be imported into an external security manager, such as RACF, and associated with the key ring that is specified in the KEYRING system initialization parameter. For outbound SOAP messages, you generate and publish the public key to the intended recipients. The Integrated Cryptographic Service Facility (ICSF) is used to generate public keys.

When you specify the label associated with an X.509 digital certificate, do not use the following characters:

< > : ! =

You can also include a second X.509 certificate in the header and sign it using the first certificate. With this second certificate, you can run the work in CICS under the user ID associated with the second X.509 certificate. The certificate that you are using to sign the SOAP message must be associated with a trusted user ID, and have surrogate authority to assert that work runs under a different identity, the asserted identity, without the trusted user ID having the password associated with that identity.

Encrypting

In service provider and service requester mode, you can encrypt the SOAP message body using a symmetric algorithm such as Triple DES or AES. A symmetric algorithm is where the same key is used to encrypt and decrypt the data. This key is known as a symmetric key. It is then included in the message and encrypted using a combination of the public key of the intended recipient and the asymmetric key encryption algorithm RSA 1.5. This encryption provides you with increased security, because the asymmetric algorithm is complex and it is difficult to decrypt the symmetric key. However, you obtain better performance because the majority of the SOAP message is encrypted with the symmetric algorithm, which is faster to decrypt.

For inbound SOAP messages, you can encrypt an element in the SOAP body and then encrypt the SOAP body as a whole. This sort of encryption might be particularly appropriate for an element that contains sensitive data. If CICS receives a SOAP message with two levels of encryption, CICS decrypts both levels automatically. This sort of encryption is not supported for outbound SOAP messages.

CICS does not support inbound SOAP messages that have an encrypted element in the message header only and no encrypted elements in the SOAP body.

Signing and encrypting

In service provider and service requester mode, you can choose to both sign and encrypt a SOAP message. CICS always signs the SOAP message body first and then encrypts it. The advantage of this method is that it gives you both message confidentiality and integrity.

ICRX-based identity propagation

In service provider mode, you can use an unauthenticated ICRX (Extended Identity Context Reference) identity token in the same circumstances that you would use an unauthenticated WS-Security user ID token. An ICRX identity token is a z/OS identifier that maps to a user ID. CICS resolves the ICRX identity token to a user ID and places a copy in the DFHWS-ICRX container. CICS also populates the DFHWS-USERID container. For more information about an ICRX identity token, see Identity propogation and distributed security.