Run the SOAP security samples

The process for running the SOAP signed samples is identical to the process for running the nonsigned samples. You must install the soapsamples.ear file, and start the server before you invoke these samples.

Set up the samples

Perform these steps to install the samples on your server:

  1. Install the soapsamples.ear EAR file, which is located in the /QIBM/ProdData/WebAS5/InstallableApps directory.
    1. If you have not already done so, map a drive to your iSeries server.
    2. At a workstation command prompt, change the working directory to /QIBM/ProdData/WebAS5/bin.
    3. Install the EAR file by entering this command: 
      /QIBM/ProdData/WebAS5/Base/bin/wsadmin -instance your_instance -c 
'$AdminApp install /QIBM/ProdData/WebAS5/Base/installableApps/soapsamples.ear 
{ -appname Apache-SOAP_Samples -node node_name}'

      where your_instance is the name of your instance and node_name is the name of the node to which your is installed.

      If the soapsamples.ear file is not present, you can download it from the Websphere Developer's Domain Link outside Information Center.

  2. Authorize OS/400 user profile QEJBSVR to the following directory with *RWX and all object authorities:
    /QIBM/Userdata/WebAS5/Base/instance_name/installedApps/Apache-SOAP_Samples.ear/soapsec.war/log
  3. Start or restart the HTTP server.

    Note: You only need to perform this step if you added the plugin for the first time.

  4. Check on the availability of the sample services using the XML-SOAP Admin tool:
    1. From a browser, go to http://my_iSeries:port_number/soapsamples/admin/index.html, where my_iSeries is the host name of your iSeries server and port_number is the port that corresponds to the HTTP server instance associated with your instance of WAS.
    2. Perform any of these administrative tasks:

      • List available services
      • View the Apache SOAP descriptors
      • Stop and start sample services

Running the sample clients

The client samples are included in the soapsamples.ear file. Perform these steps to locate and run the samples:

Note: If you run the scripts with no arguments, you are provided with help with using the sample, and you receive a description of the command line arguments that the script requires. These scripts set the classpath and supply parameters.

To run the sample clients, perform these steps:

  1. At a workstation command prompt, navigate to /QIBM/UserData/WebAS5/Base/instance_name/installedApps/soapsamples.ear/ClientCode. Then invoke one of the following files:

    • On Windows systems, nt_bat
    • On UNIX systems, unix_script

      Note: Issue the chmod 755 *.sh command to restore the execution permissions of the UNIX scripts.

  2. Run any of the sample scripts: 
    DSigAddressSample my_iSeries:port_number 
"/QIBM/UserData/WebAS5/Base/instance_name/installedApps/soapsamples.ear"
"John B. Good"

DSigMessageSample my_iSeries:port_number 
"/QIBM/UserData/WebAS5/Base/instance_name/installedApps/soapsamples.ear"
..\data\msg1.xml
    where my_iSeries is the host name of your iSeries server and port_number is the port corresponding to the HTTP server instance associated with your instance of WAS.
  3. View the information that the scripts output. For each sample, the server displays the signature of the request that is validated. The client displays the signature of the response that is validated.
  4. The validation results for both the client and server are written to these files that are created in the /QIBM/UserData/WebAS5/Base/instance_name/installedApps/soapsamples.ear/soapsec.war/logs (where instance name is the root directory of your WAS instance):

    • SOAPVHH-all-cl.log
    • SOAPVHH-fail-cl.log
    • SOAPVHH-all-sv.log
    • SOAPVHH-fail-sv.log

Use SOAP signatures with SSL

Optionally, you can authenticate requests for SOAP services by using both SOAP signatures in conjunction with the Secure Sockets Layer (SSL) protocol. This process requires additional setup for your HTTP server. To ensure that the HTTP server can authenticate a client's authority to Web services, install the test digital certificates into your Web server's SSL key database.

Install the test digital certificates is a two step process: first export the client certificates from the test keystore file, then import them into the HTTP server's key database.

  1. Export the client certificates.
    1. If you have not already done so, map or mount a network drive on your workstation to your iSeries server.
    2. Start the iKeyman tool.
    3. From the File menu, select Open.
    4. In the Open dialog, navigate to the user_install_root/installedApps/cell_name/Apache-SOAPSamples.ear/soapsec.war/key/ directory.
    5. Select the SOAPClient keystore file. The keystore password is client.
    6. Change the key database content type to Signer Certificates.
    7. Select the soapca certificate.
    8. Click Export.
    9. Change the exported file name to soapca.arm.
    10. Select the intca1 certificate.
    11. Click Export.
    12. Change the exported file name to intca1.arm.

  2. Import the client certificates.

    Note: These instructions assume that the Web server is configured for SSL, and the Web server's certificate is signed by the iSeries system's local certificate authority.

    1. Start the Digital Certificate Manager (DCM).
    2. Add the signer certificates to the *SYSTEM keystore.
      1. Click Select a Certificate Store.
      2. Select *SYSTEM and click Continue.
      3. On the Certificate Store and Password page, enter the password, then click Continue.
      4. On the left pane, click Fast Path.
      5. Select Work with CA certificates and click Continue.
      6. To import both the soapca.arm and intca1.arm files, perform these steps:
        1. Click Import.
        2. In the Import file field, specify the fully-qualified path of the file.
        3. click Continue.
        4. In the CA certificate label field, specify the appropriate value:

          • For soapca.arm, specify soapca.
          • For intca1.arm, specify intca1.

        5. Click Continue.

      7. Select Work with server and client certificates, and click Continue.
      8. Click Import.
      9. In the Import file field, specify the fully-qualified path of the file user_install_root/installedApps/cell_name/Apache-SOAPSamples.ear/soapsec.war/key/sslserver.p12, and click Continue.
      10. The keystore password is server.
      11. Save and exit DCM.

Troubleshooting SOAP samples

If you cannot run the SOAP security samples, check for these problems: