Example: Configuring the client authentication and basic authentication security scheme

This example demonstrates how to create self-signed certificates to configure client authentication and basic authentication when the web service is hosted on an Apache Tomcat server on Windows. The actual location of the key management utility might be different based on your server environment.

In this example, the Apache Tomcat server that hosts the web service is referred to as the server and is installed on a Windows system. SOAP Gateway is referred to as the client (that is requesting a web service) and is installed on a z/OS system.

To configure client authentication and basic authentication for callout requests:

  1. On the web service server, create the server keystore and truststore, and export the server certificate.
    1. In a command prompt, change the directory to the location of the keytool program on the Apache server (for example, server_dir\java\jre\bin).
    2. Create a keystore (server.keystore.ks): 
      keytool -genkey -alias server.keystore -dname "CN=hostname.company.com 
OU=IBM SWG, O=IBM, C=US" -keyalg RSA -keypass password 
-storepass password -keystore "<path_to>\server.keystore.ks"
      The CN value must be a valid hostname. The exact hostname must be specified in the callout web service WSDL endpoint. For example,
      <wsdl:service name="IMSSOAPCalloutService">
  <wsdl:port binding="tns:IMSSOAPCalloutBinding" name="IMSSOAPCalloutPort">
    <soap:address location=
     "https://hostname.company.com:8443/imssoap/services/IMSSOAPCalloutService"/>
  </wsdl:port>
      If the hostname in the server keystore and the hostname in the callout WSDL file do not match, an IOGS0077E error occurs:
      IOGS0077E: An error occurred during the invocation of the external web 
service: hostname in certificate didn't match: 
<hostname1.company.com> != <hostname2.company.com>
      For NIST SP800-131a, specify SHA256withRSA for the signature algorithm and 2048 for the key size.
      keytool -genkey -alias server.keystore -dname 
"CN=hostname.company.com OU=IBM SWG, O=IBM, C=US" 
-keyalg RSA -sigalg SHA256withRSA  -keysize 2048 
-keypass password -storepass password 
-keystore "<path_to>\server.keystore.ks"
    3. Create a truststore (server.truststore.ks): 
      keytool -genkey -alias server.truststore -dname "CN=Server Truststore, 
OU=IBM SWG, O=IBM, C=US" -keyalg RSA -keypass password 
-storepass password -keystore "<path_to>\server.truststore.ks"
      For NIST SP800-131a, specify SHA256withRSA for the signature algorithm and 2048 for the key size.
      keytool -genkey -alias server.truststore -dname 
"CN=Server Truststore OU=IBM SWG, O=IBM, C=US" 
-keyalg RSA -sigalg SHA256withRSA  -keysize 2048 
-keypass password -storepass password 
-keystore "<path_to>\server.truststore.ks"
    4. Export the server certificate (server.keystore.cer) from the server keystore: 
      keytool -export -alias server.keystore -storepass password 
-file server.keystore.cer -keystore "<path_to>\server.keystore.ks"
  2. On the client (SOAP Gateway), create the client keystore and truststore, and export the client certificate.
    1. In a command prompt, change the directory to the location of the keytool program.
    2. Create the keystore (callout.client.keystore.ks): 
      keytool -genkey -alias callout.client.keystore -dname 
"CN=IMS Callout Client Keystore, OU=IBM SWG, O=IBM, C=US" -keyalg RSA 
-keypass password -storepass password 
-keystore <path_to>/callout.client.keystore.ks
    3. Create a truststore (callout.client.truststore.ks): 
      keytool -genkey -alias callout.client.truststore -dname 
"CN=IMS Callout Client Truststore, OU=IBM SWG, O=IBM, C=US" -keyalg RSA 
-keypass password -storepass password 
-keystore <path_to>/callout.client.truststore.ks
    4. Export the client certificate (callout.client.keystore.cer) from the client keystore: 
      keytool -export -alias callout.client.keystore -storepass password 
-file <path_to>/callout.client.keystore.cer -keystore <path_to>/callout.client.keystore.ks
  3. Transfer the web service server certificate to the location of the client (SOAP Gateway) truststore (or a location that the client can access).
  4. Transfer the client (SOAP Gateway) certificate to the location of the server truststore (or a location that the server can access).
  5. On the server, import the client certificate and configure the server to point to the keystore and truststore.
    1. Go to the server directory that contains Java™.
    2. Import the client certificate (callout.client.keystore.cer): 
      keytool -import -v -trustcacerts -alias callout.client 
-file callout.client.keystore.cer -keystore "<path_to>\server.truststore.ks" 
-keypass password -storepass password
    3. Modify the server.xml file to point to the keystore and truststore with the appropriate passwords.
      • Set clientAuth to true.
      • Set sslProtocol to SSL.
      • For NIST SP800-130a:
        • Add the following attributes if they do not yet exist:
          SSLEnabled="true"
sslEnabledProtocols="TLSv1.2"
        • Remove the sslProtocol attribute if it is present.
      • Specify the file location for keystore and truststore.
      • Specify the password for keystore and truststore.

      The following example demonstrates the settings when the IbmX509 algorithm is used with an IBM® Java Runtime Environment (JRE). For the SUN JRE, set the algorithm attribute to SunX509. This example has client authenticated specified, but is not FIPS-enabled and does not support NIST SP800-130a.

      <!-- Define a SSL HTTP/1.1 Connector on your port --> 
<Connector SSLEnabled="true"
acceptCount="100" algorithm="IbmX509" clientAuth="true" 
disableUploadTimeout="true" enableLookups="false" 
keystoreFile="<path_to>\server.keystore.ks" 
keystorePass="password" 
maxThreads="150" minSpareThreads="25" port="8663" 
scheme="https" secure="true" sslProtocol="SSL"  


      truststoreFile="<path_to>\server.truststore.ks" 
truststorePass="password"/>
      To support NIST SP800-130a, remove the sslProtocol attribute, and add sslEnabledProtocols attributes.
      <!-- Define a SSL HTTP/1.1 Connector on your port --> 
<Connector SSLEnabled="true"
acceptCount="100" algorithm="IbmX509" clientAuth="true" 
disableUploadTimeout="true" enableLookups="false" 
sslEnabledProtocols="TLSv1.2"
keystoreFile="<path_to>\server.keystore.ks"  
keystorePass="password" 
maxThreads="150" minSpareThreads="25" port="8663" 
scheme="https" secure="true"  


      truststoreFile="<path_to>\server.truststore.ks" 
truststorePass="password"/>
  6. On the server, configure basic authentication.
    1. Add a role for the user credentials and for the client certificate by modifying the tomcat-users.xml file in the server_dir\server\conf\ directory.
      The following example demonstrates the specification of a callout user (imsuser) with password imspwd.
      <role rolename="imsuser"/>
<user username="imsuser" password="imspwd" roles="imsuser"/>

<!-- Add the client certificate as a user to tomcat -->
<user username="CN=IMS Callout Client Keystore, OU=IBM SWG, O=IBM, C=US" 
password="null" roles="admin"/>
    2. Add the security constraints and login configurations to a specific web service by modifying the web.xml file in the server_dir\server\webapps\imssoap\WEB-INF\ directory.
      For example: 
      <security-constraint>
   <web-resource-collection>
      	<web-resource-name>Protected</web-resource-name>
      	<!-- Specify the directory for restricted web Services application -->
     	<url-pattern>/servlet/YourServlet</url-pattern>
   </web-resource-collection>
   <auth-constraint>
      	<!-- Specify the role name of the new user -->
      	<role-name>imsuser</role-name>
   </auth-constraint>
</security-constraint>

<!-- Define the Login Configuration for this Application -->
<login-config>
   <auth-method>BASIC</auth-method>
   <realm-name>Protected Web Services</realm-name>
</login-config>
  7. On the client (SOAP Gateway), import the server certificate (server.keystore.cer):
    1. Go to the directory that contains the keytool program.
    2. Import the server certificate (server.keystore.cer). 
      keytool -import -v -trustcacerts -alias server 
-file <path_to>/server.keystore.cer 
-keystore <path_to>/callout.client.truststore.ks -keypass password 
-storepass password
  8. On the client, configure the callout security by using the SOAP Gateway management utility.
    Use the iogmgmt -conn command to specify the callout security information. For example:
    iogmgmt -conn -c -n MyCalloutConnBundle -h ICONHOST -p 9998
-d IMSSTOR1 -i tpipe1 
-l callout_target_ks_name -y callout_target_ks_pwd 
-v callout_target_ts_name -q callout_target_ts_pwd
-m callout_target_basic_auth_id -b callout_target_basic_auth_pwd
The configuration of client authentication and basic authentication is completed.