Enabling operation-level authorization

Use this task to apply security to individual methods in a Web service.

Before you begin

Before you begin this task you must first enable gateway-level authentication.

You can only apply operation-level authorization to a Web service that is already deployed to the gateway with the check box "Authorization Policy - Control access to this service" enabled.

Why and when to perform this task

For operation-level authorization you create an enterprise bean with methods matching the Web service operations. These EJB methods perform no operation and are just entities for applying security. You can apply existing WebSphere Application Server 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 wsgwauth.ear file and the wsgwauth.ear file is modified to set the roles and assign them to methods. The modified wsgwauth.ear file is then deployed in WebSphere Application Server, and users are assigned to the previously-defined roles.

The wsgwauth.ear file contains an EAR file for each Web service that you protect. The installation version of the wsgwauth.ear file is in install_root/installableApps, where install_root is the root directory for your installation of IBM WebSphere Application Server (by default WebSphere/AppServer). For the first Web service that you protect through operation-level authorization, you copy the installation version of the wsgwauth.ear file and store your copy outside of the application server file system. For each subsequent Web services that you protect, you further modify the same copy of the wsgwauth.ear file.

To enable operation-level authorization, you use the WSGWAuthGen command, and the Assembly Toolkit. You can only use the tool on a Windows system, so you have to copy (in binary) to a Windows system all the files you need for this task, then create and modify the EAR files on the Windows system, then copy (in binary) the modified wsgwauth.ear file back to your z/OS system.

To enable Web service operation-level authorization, complete the following steps for each Web service that you want to protect:

Steps for this task

  1. For the first Web service that you protect, complete the following steps:
    1. Make your own copy of the install_root/installableApps/wsgwauth.ear file in a convenient location outside of the application server file system.
    2. On your Windows system, install the Assembly Toolkit.
    3. On your Windows system, create a directory with a name of your 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 your new directory (for example /your_dir):

      • install_root/WSGW/scripts/auth/WSGWAuthGen.bat
      • install_root/WSGW/scripts/auth/WSGWAuthGen.jar

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

      • install_root/lib/commons-logging-api.jar
      • install_root/lib/j2ee.jar
      • install_root/lib/qname.jar
      • install_root/lib/wsdl4j.jar
      • install_root/lib/wsif.jar
      • install_root/lib/xerces.jar
  2. Use File Transport Protocol (FTP) to copy (in binary) your own copy of the wsgwauth.ear file from your z/OS system into your directory (for example /your_dir) on your Windows system.
  3. To create the your_webservice.ear file, complete the following steps:
    1. Open a command prompt on the Windows system.
    2. Go to your directory (for example your_dir).
    3. Enter one of the following commands to set the WAS_HOME environment variable to point to your new directory:
      set WAS_HOME=path_to_new_directory
      or
      set WAS_HOME=.
      where path_to_new_directory is the full path to your new directory (for example C:\your_dir).
    4. [Version 5.0.2]Enter one of the following commands to set the path to point to the Java Virtual Machine (JVM) that is supplied with the assembly tool that you installed:

      If you installed the Assembly Toolkit, and accepted the default path for the JVM, enter the following command:

      PATH=C:\Program Files\IBM\ASTK\runtimes\base_v5\java\bin
      If you installed the Application Assembly Tool, and accepted the default path for the JVM, enter the following command:
      PATH=C:\Programs\IBM\WebSphereClientDevelopmentKitforzOS\java\bin
    5. 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;

    6. Enter the following command:
      WSGWAuthGen location your_webservice
      where:
      • location is the Web address for the gateway. This must include the root context.
      • your_webservice is the name of the service as deployed in the gateway. This is case-sensitive.
      For example
      WSGWAuthGen http://host:port/wsgw AddressBook
      where host and port are the host name and port number for the application server on which the gateway is installed.

      The Web service name and operation name can contain characters (such as a dash (-), period (.) and ampersand (&)) that are disallowed in an EJB class name and method name. Therefore these are translated during the generation process of the your_webservice.ear file. A message appears informing you of any name changes.

    The your_webservice.ear file is created in the current directory. There is also a temporary directory current_directory/ejb that you can delete.
  4. To finish assigning roles and protecting methods, complete the steps given in the following topic:
  5. To install the modified copy of the wsgwauth.ear file, complete the following steps:
    1. Use FTP to copy (in binary) the modified wsgwauth.ear file back to the convenient location on your z/OS system that you chose in step 1. Store the modified wsgwauth.ear file in this location for subsequent reuse and further modification.
    2. Start the WebSphere Application Server administrative console.
    3. In the navigation pane, select Applications > Install an Application.
    4. Use Install New Application to install the modified copy of the wsgwauth.ear file. Select the users or groups to assign to the roles when prompted.

Related concepts
Operation-level security - role-based authorization
Related tasks
Securing the Web services gateway
Enabling gateway-level authentication
Invoking Web services over HTTPS
Troubleshooting the Web services gateway



Searchable topic ID:   twsg_security_wslevel
Last updated: Jun 21, 2007 9:56:50 PM CDT    WebSphere Application Server for z/OS, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/twsg_security_wslevel.html

Library | Support | Terms of Use | Feedback