[Version 5.0.2 and later]Configuring the was.policy file

Before you begin

Java 2 security uses several policy files to determine the granted permission for each Java program. See Java 2 security policy files for the list of available policy files supported by WebSphere Application Server Version 5. The was.policy file is an application-specific policy file for WebSphere Application Server enterprise applications. It is embedded in the enterprise archive (EAR) file (META-INF/was.policy). The was.policy file is located in:
install_root/config/cells/cell_name/applications/
ear_file_name/deployments/application_name/META-INF/was.policy

The union of the permission contained in the java.policy file, the server.policy file, the app.policy file, application was.policy file and the permission specification of the ra.xml file are applied to the WebSphere Application Server enterprise application. Configuration and file replication services manage was.policy files. Changes made in these files are replicated to other nodes in the Network Deployment cell.

Several product-reserved symbols are defined to associate the permission lists to a specific type of resources.

Symbol Definition
file:${application} file:${application}
file:${jars} Permissions apply to all utility Java archive (JAR) files within the application
file:${ejbComponent} Permissions apply to enterprise bean resources within the application
file:${webComponent} Permissions apply to Web resources within the application
file:${connectorComponent} Permissions apply to connector resources within the application


Note: The Signed By and the Java Authentication and Authorization Service (JAAS) principal keywords are not supported in the was.policy file. The Signed By keyword is supported in the following policy files: java.policy, server.policy, and client.policy. The JAAS principal keyword is supported in a JAAS policy file when it is specified by the Java Virtual Machine (JVM) system property, java.security.auth.policy. You can statically set the authorization policy files in java.security.auth.policy with auth.policy.url.n=URL where URL is the location of the authorization policy.

Other than these blocks, you can specify the module name for granular settings. For example,

"file:DefaultWebApplication.war" {
      permission java.security.SecurityPermission "printIdentity";
 };

grant codeBase "file:IncCMP11.jar" {
      permission java.io.FilePermission 
      "${user.install.root}${/}bin${/}DefaultDB${/}-", 
      "read,write,delete";
};

There are five embedded symbols provided to specify the path and name for the java.io.FilePermission. These symbols enable flexible permission specification. The absolute file path is fixed after the application is installed.

Symbol Definition
${app.installed.path} Path where the application is installed
${was.module.path} Path where the module is installed
${current.cell.name} Current cell name
${current.node.name} Current node name
${current.server.name} Current server name


Why and when to perform this task

If the default permissions for the enterprise application (union of the permissions defined in the java.policy file, the server.policy file and the app.policy file) are enough, no action is required. If an application has specific resources to access, update the was.policy file. The first two steps assume that you are creating a new policy file.

Note: Syntax errors in the policy files cause the application server to fail. Use care when editing these policy files.

Steps for this task

  1. Create or edit a new was.policy file using the Policy Tool.
    For more information, see Using PolicyTool to edit policy files
  2. [5.0 only][Version 5.0.1]Package the was.policy file into the enterprise archive (EAR) file.
    For more information, see Adding the was.policy file to applications.
    1. Start the Application Assembly Tool (AAT).
    2. Click File > Open.
    3. Navigate through the directory tree to find and update the application EAR file.
    4. Click Open. The EAR file loads.
    5. In left panel, click Files. A list of the files displays in the right panel.
    6. Right-click the was.policy file in the right panel, if the was.policy file already exists. Click Delete to remove the existing was.policy file.
    7. Right-click Files in the left panel. Select Add Files.
    8. Click Browse. Navigate to the was.policy file.
    9. Click Select. The directory contents display in the Add Files window.
    10. Navigate to the was.policy file. Click Add. The selected was.policy file displays in the right panel.
    11. Click File > Verify to verify the EAR file. Verify that the was.policy file is validated.
    12. Click File > Save to save the updated EAR file.
  3. [Version 5.0.2 and later]Package the was.policy file into the enterprise archive (EAR) file.

    For more information, see Adding the was.policy file to applications.

    The following instructions describe how to import a was.policy file. However, you also can use the Assembly Toolkit to create a new file by clicking File > New > File.
    1. Start the Assembly Toolkit and open the J2EE Perspective by selecting Window > Open Perspective > J2EE.
    2. Import the client EAR file by selecting File > Import > EAR file.
    3. Click Next.
    4. Enter the path name to the EAR file in the EAR File field or click Browse to locate the file.
    5. Enter the project name in the Project name field.
    6. Click Finish.
    7. Open the Project Navigator view.
    8. Expand the EAR file and click META-INF.
      You might find a was.policy file in the META-INF directory. If you want to delete the file, right-click the file name and select Delete.
    9. At the bottom of the Project Navigator view, click J2EE Hierarchy.
    10. Import the was.policy file by right-clicking the Modules directory and clicking Import > File system.
    11. Click Next.
    12. Enter the path name to the was.policy file in the From directory field or click Browse to locate the file.
    13. Verify that the path directory listed in the Into directory field lists the correct META-INF directory.
    14. Click Finish.
    15. To validate the EAR file, right-click the EAR file, which contains the Modules directory, and click Run Validation.
    16. To save the new EAR file, right-click the EAR file, and click Export > Export EAR file.
      If you do not save the revised EAR file, the EAR file will contain the new was.policy file. However, if the workspace becomes corrupted, you might lose the revised EAR file.
    17. To generate deployment code, right-click the EAR file and click Generate Deployment Code.
  4. Update an existing installed application, if one already exists.
    1. Modify the was.policy file with the Policy Tool.
      For more information, see Using PolicyTool to edit policy files.
    2. Extract the policy file.
      Enter the following from a command prompt:
      wsadmin  wsadmin>  set obj [$AdminConfig extract cells/cell_name
      /application/ear_file_name/deployments/application_name
      /META_INF/was.policy c:/temp/test/was.policy]

      Enter the three previous lines as one continuous line.

    3. Edit the extracted was.policy file with the Policy Tool.
      Form more information, see Using PolicyTool to edit policy files.
    4. Check in the policy file.
      Enter the following at a command prompt:
      wsadmin> $AdminConfig checkin cells/cell_name/application/
      ear_file_name/deployments/application_name/META_INF/was.policy 
      c:/temp/test/was.policy $obj

      Enter the three previous lines as one continuous line.

Results

The updated was.policy file is applied to the application after the application restarts.

Example

java.policyserver.policyapp.policywas.policyjava.security.AccessControlExceptionjava.security.AccessControlException: access denied (java.io.FilePermission C:\WebSphere\AppServer\java\jre\lib\ext\mail.jar read)

When a Java program receives this exception and adding this permission is justified, add a permission to the was.policy file: grant codeBase "file:<user client installed location>" { permission java.io.FilePermission "C:\WebSphere\AppServer\java\jre\lib\ext\mail.jar", "read"; };.

To determine whether to add a permission, refer to the article, AccessControlException.

What to do next

Restart all applications for the updated app.policy file to take effect.

Related concepts
AccessControlException
Java 2 security policy files
Related tasks
Migrating security configurations from previous releases
Configuring spi.policy files
Configuring library.policy files
Adding the was.policy file to applications



Searchable topic ID:   tsecwaspolicyfile
Last updated: Jun 21, 2007 4:55:42 PM CDT    WebSphere Application Server Network Deployment, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/tsec_waspolicyfile.html

Library | Support | Terms of Use | Feedback