Password-protecting a web service operation

Password-protect individual operations (methods) in a Web service by creating an enterprise bean with methods matching the Web service operations, then applying WebSphere Application Server authentication mechanisms to the enterprise bean so that, before a web service operation is invoked, a call is made to the EJB method for authorization.

As well as password-protecting a web service operation as described in this topic, we must also configure the service as either an inbound or outbound service, and select the option to Enable operation-level security as described in Modifying an existing inbound service configuration or Modifying an existing outbound service configuration.

In order for an application deployed to the service integration bus to use operation-level security, set the application server class-loader policy to "single", as described in Configure class loaders of a server.

For operation-level authorization we create an enterprise bean with methods matching the web service operations. These EJB methods perform no operation and are just entities for applying security. We then apply existing WAS authentication mechanisms to the enterprise bean. Before any web service operation is invoked, a call is made to the EJB method. If authorization is granted, the web service is invoked.

Your target web service is protected by wrapping it in an EAR file (your_webservice.ear), then applying role-based authorization to the EAR file. This process is explained in general terms in Operation-level security: Role-based authorization. The your_webservice.ear file is then imported into the sibwsauthbean.ear file and the sibwsauthbean.ear file is modified to set the roles and assign them to methods. The modified sibwsauthbean.ear file is then deployed in WAS, and users are assigned to the previously-defined roles.

The installation version of the sibwsauthbean.ear file is in the app_server_root/installableApps directory, where app_server_root is the root directory for the installation of WAS.

The sibwsauthbean.ear file contains an EAR file for each web service that you protect. For the first web service that you protect through operation-level authorization, you copy the installation version of the sibwsauthbean.ear file and store your copy outside of the application server file system. For each subsequent web service that you protect, you further modify the same copy of the sibwsauthbean.ear file.

(ZOS) To enable operation-level authorization, we use the sibwsAuthGen command, and an assembly tool. We can only use these tools on a Windows system, so we must copy (in binary) to a Windows system all the files we need for this task, then create and modify the EAR files on the Windows system, then copy (in binary) the modified sibwsauthbean.ear file back to your z/OS system.

To password-protect web service operations for each web service to protect:

Tasks

1. (iSeries) (Dist) For the first web service that you protect, make our own copy of the app_server_root/installableApps/SIBWSauthbean.ear file in a convenient location outside of the application server file system.

2. For the first web service that you protect, complete the following steps:

   1. Make our own copy of the app_server_root/installableApps/SIBWSauthbean.ear file in a convenient location outside of the application server file system.

   2. On your Windows system, install the assembly tool.

   3. On your Windows system, create a directory with a name of our own choosing (for example /your_dir) and in that directory create a subdirectory called lib.

   4. Use File Transport Protocol (FTP) to copy (in binary) the following files from your target application server under z/OS to your Windows system:

      Copy the following files into the new directory (for example /your_dir):

      • app_server_root/util/SIBWSAuthGen.bat

      Copy the following files into the new lib subdirectory (for example /your_dir/lib):

      • app_server_root/lib/commons-logging-api.jar
      • app_server_root/lib/qname.jar
      • app_server_root/lib/wsdl4j.jar
      • app_server_root/lib/wsif.jar
      • app_server_root/lib/xerces.jar

3. Use File Transport Protocol (FTP) to copy (in binary) our own copy of the sibwsauthbean.ear file from your z/OS system into your directory (for example /your_dir) on your Windows system.

4. To create the your_webservice.ear file, complete the following steps:

   1. (iSeries) (Dist) Open a command prompt.

   2. (iSeries) (Dist) Go to the app_server_root/util directory.

   3. Open a command prompt on the Windows system.

   4. Go to your directory (for example your_dir).

   5. Enter one of the following commands to set the WAS_HOME environment variable to point to the new directory:

      set WAS_HOME=path_to_new_directory
      

      or

      set WAS_HOME=.
      

      where path_to_new_directory is the full path to the new directory .

   6. Set the path to point to the Java virtual machine supplied with the assembly tool.

   7. Enter the following command to update the class path:

      set classpath=lib\commons-logging-api.jar;lib\j2ee.jar;lib\qname.jar;lib\wsdl4j.jar;lib\wsif.jar;lib\xerces.jar;
      

   8. Enter the following command:

      sibwsAuthGen location your_webservice_name
      

      where
      • location is the service WSDL location. For an outbound service, we need the target WSDL file located at an external web address. For an inbound service, we need the template WSDL file located at the endpoint listener endpoint for the service.
      • your_webservice_name is the name of the service that we are securing, as defined in the location field of the WSDL file. This is case-sensitive.

      To get the location details for a given inbound service WSDL file, publish the WSDL file to a compressed file as described in Modifying an existing inbound service configuration, then look up the location within the exported WSDL file. Alternatively, we can retrieve the inbound service WSDL file using the following standard web services query:

      http://host_name:port_number/epl_context_root/soaphttpengine/bus_name/inbound_service_name/inbound_port_name?wsdl
      

      where host_name and port_number are the host name and port number for this application server, and epl_context_root is the context root of the endpoint listener application as described in Modifying an existing endpoint listener configuration.

      Examples of using the sibwsAuthGen command:

      (outbound service):

      sibwsAuthGen http://www.somecompany.com/targetservice/wsdl/targetservice.wsdl targetServiceName
      

      (inbound service):

      sibwsAuthGen http://your.server.name:9080/wsgwsoaphttp1/soaphttpengine/yourbus/ourservice/inboundport1?wsdl ourservicename
      

   The your_webservice.ear file is created in the current directory. There is also a temporary directory current_directory/ejb that we can delete.

5. To finish assigning roles and protecting methods, complete the steps given in the topic Use assembly tools to Password-protect a web service operation.

6. To install the modified copy of the sibwsauthbean.ear file, complete the following steps:

   1. (iSeries) (Dist) Check that the modified sibwsauthbean.ear file is stored in the convenient location outside of the application server file system that we chose in step 1. Keep the sibwsauthbean.ear file in this location for subsequent reuse and further modification.

   2. Use FTP to copy (in binary) the modified sibwsauthbean.ear file back to the convenient location on your z/OS system that we chose in step 1. Store the modified sibwsauthbean.ear file in this location for subsequent reuse and further modification.

   3. Start the WAS appservers administrative console.

   4. In the navigation pane, click...

              Applications -> New Application.

   5. Use the New Enterprise Application option to install the modified copy of the sibwsauthbean.ear file. Select the users or groups to assign to the roles when prompted.

Related:

Operation-level security: Role-based authorization

Bus-enabled web services troubleshooting tips