Security for the consumer (callout) scenario

Security support for the callout scenario is provided for messages from IMS to SOAP Gateway through SSL, and from SOAP Gateway to the web service through HTTPS. Start of changeYou can also use the z/OS® Communications Server Application Transparent Transport Layer Security (AT-TLS) feature to secure messages in the callout scenario. End of change

HTTPS encapsulates the SOAP messages from one point to another to prevent alteration to the exchanged messages. Although this level of security secures your messages and verifies your endpoints, it does not prevent execution of a web service by an unauthorized user.

To ensure that only authorized users can execute a web service, in addition to HTTPS support for invoking web services, SOAP Gateway also support passing of user information on a per web service or per message basis.
  • Basic authentication is supported by passing user name and password information in the connection bundle to the web service server. SOAP Gateway supports both the IbmX509 and SunX509 algorithms when they are configured with either the IBM® Java™ Runtime Environment (JRE) or Sun JRE that runs on the server that hosts the web service.
  • WS-Security SAML confirmation method is supported for synchronous callout applications by extracting the user ID (the user that initiates the synchronous callout application) from the correlation token and passing it to the external web service.
    Restriction: Security certificates for all external web service servers that IMS applications call out to must be stored in the same SOAP Gateway truststore because SOAP Gateway supports one truststore and one keystore per server instance.
Use different tpipes for secure and non-secure callout web services. Sharing the same tpipe for both secure and non-secure callout web services would result in problems with non-secure callout web services.
Important: You must use System SSL for communication with IMS Connect. You must apply the following fix, depending on the IMS version.
  • IMS V13 APAR PM96825
  • IMS V12 APAR PM98017

SSL security, server authentication, and client authentication

You can use SSL security between IMS Connect and SOAP Gateway, and between SOAP Gateway and the external web services to provide security for the consumer scenario. Use of SSL on either side is optional and independent of the security setting on the other side.

Regardless of the scenarios (IMS applications as web service providers or consumers), SOAP Gateway is always a client to IMS Connect. To enable the security between IMS Connect and SOAP Gateway for the web service consumer scenario, the steps are the same as the web service provider scenario:
  1. Create a truststore for SOAP Gateway to store the SSL server certificate from IMS Connect.
  2. Export the certificate from IMS Connect.
  3. Import the IMS Connect server certificate into the SOAP Gateway truststore.

When SSL security is used between SOAP Gateway and the web service, SOAP Gateway establishes security when it sends the IMS callout request to the external web service by using HTTPS. The server that hosts the web service sends back a certificate. After the transmission is secured and SOAP Gateway determines that the server certificate can be trusted, it executes the web service.

Important:

When calling out to an external web service by using HTTPS, specify the secure port as part of the URI, even if the web service uses a default secure port such as 443 or 8443. Not including a port will result in message IOGS043E. For example, the following URI is a valid external web service callout using HTTPS: https://myexternalwebservice.com:443/service/MyWebService

The following diagram shows the process flow of the server authentication process, where the web service server sends the client (SOAP Gateway) a certificate, and the client looks up the certification in its truststore and verifies that it knows the server before engaging communication.
Figure 1. Server authentication for the IMS applications as web service consumers scenario
This image shows the process flow for the SSL security scheme
  1. The client (SOAP Gateway) initiates an HTTPS call.
  2. The web service server sends back a certificate.
  3. The client verifies the certificate with the server certificate stored in the truststore.
  4. After the transmission is secure, the client is allowed to execute the services.
The following diagram shows the process flow of the client authentication security scheme, where both the server that hosts the web service and the client (SOAP Gateway) that requests the service require authentication from the other before a connection is established.
Figure 2. Client authentication for the IMS applications as web service consumers scenario
This image shows the process flow for the client authentication security scheme
  1. The client initiates an HTTPS call.
  2. The server sends back a certificate.
  3. The client verifies the certificate with the server certificate that is stored in the truststore.
  4. The client sends the server a certificate.
  5. The server verifies the client certificate with the certificate that is stored in the truststore.
  6. After the transmission is secured, the client is authenticated and allowed to access protected services.
Important: If the SOAP Gateway client and the web service are hosted on the same system, do not use the same JRE for both SOAP Gateway and your server. The runtime environments must be different instances of a JRE. Otherwise, the JVM cannot distinguish whether the keystore belongs to the client or the server.

Basic authentication security scheme

Basic authentication means that the server that hosts the web service requires the client (SOAP Gateway) to have proper basic authentication credentials in order to invoke a service. The client transmits the credentials during the invocation of a web service.

The user ID and password for basic authentication are stored in the connection bundle. The user ID and password are specified when you generate the connection bundle for a callout web service by using the SOAP Gateway management utility. SOAP Gateway retrieves the pre-defined basic authentication security token from the connection bundle and passed it to external web service.

Basic authentication can be used with or without HTTPS. Without HTTPS, the user name and password information is transmitted in clear text.

Recommendation: Use basic authentication with HTTPS support to ensure that user name and password information is not transmitted in clear text.
The following diagram shows the basic authentication security scheme:
Figure 3. Basic authentication for the IMS applications as web service consumers scenario
This image shows the process flow for the basic authentication security scheme
  1. The client (SOAP Gateway) initiates a request for the protected service.
  2. SOAP Gateway retrieves the basic authentication user ID and password information that is stored in the connection bundle.
  3. The web service server requests basic authentication information (user ID and password).
  4. The client sends the authentication information.
  5. After the transmission is secure, the server returns the requested service.
You can use server authentication and basic authentication together. SOAP Gateway supports the following combinations of web service callout security scenarios:
  • Server and basic authentication
  • Client authentication
  • Client authentication and basic authentication