Customizing security in WebSphere Application Server

If the default security roles and configuration defined for the Report Launcher for Rational® ClearQuest® do not meet your requirements, you can change it by updating the Report Launcher for Rational ClearQuest deployment descriptor file. After updating this file, use the WebSphere® Application Server wsadmin utility to apply the deployment descriptor settings.

About this task

This task is required only if you want to customize the default report launcher security roles and configuration described in Configuring security for the Report Launcher and reports.

Before customizing the security configuration, consider the security behavior that you are trying to achieve. For example, do you want all users to authenticate when they start the Report Launcher? Do you want to provide different report access rights to different users or groups? Review Example security configuration settings as a starting point for updating the configuration.

Update the Report Launcher for Rational ClearQuest deployment descriptor to configure client authentication on the WebSphere Application Server.

Procedure

Copy the Report Launcher for Rational ClearQuest deployment descriptor file web.xml to a working directory and rename the file. The web.xml file is located in this directory:
Windows:
```
cd %CLEARQUEST_HOME%\cqweb\cqwebprofile\installedApps\dfltCell\RationalClearQuestReportLauncher.ear\CQReportLauncher.war\WEB-INF\web.xml
```
UNIX and Linux:
```
cd $CLEARQUEST_HOME/cqweb/cqwebprofile/installedApps/dfltCell/RationalClearQuestReportLauncher.ear/CQReportLauncher.war/WEB-INF/web.xml
```
Note: The default WebSphere Application Server cell directory is dfltCell on Windows, UNIX, and Linux platforms. On the Solaris platform, the default is <srv>Node01Cell.
The remaining steps in this procedure assume that you renamed the web.xml file copied to the working directory to launcher_web.xml.
Update the security-constraint and security-role elements to change the security settings. Modification of the login-config element is not necessary. For ideas about possible configurations, see Example security configuration settings.
Use the WebSphere Application Server wsadmin utility to apply the deployment descriptor changes:
1. From a command prompt, change the working directory to the directory that contains the launcher_web.xml file.
2. From a command prompt, run this command to start the wsadmin utility:
  Windows:
```
%CLEARQUEST_HOME%\cqweb\cqwebprofile\bin\wsadmin
```
  UNIX and Linux:
```
%CLEARQUEST_HOME%cqweb/cqwebprofile/bin/wsadmin.sh
```
3. Supply the credentials for the WebSphere administrative user if prompted.
4. Run these commands to update the deployment descriptor in WebSphere Application Server:
```
wsadmin> $AdminApp update RationalClearQuestReportLauncher file {-operation update -contents launcher_web.xml -contenturi CQReportLauncher.war/WEB-INF/web.xml}
wsadmin> $AdminConfig save
wsadmin> exit
```

Example security configuration settings

You can use the following code samples as a starting point for configuring Report Launcher application security in your environment.

Example 1: Require all users to logon to Report Launcher to access reports

This code sample shows security configuration settings that provide all users with logon access to the Report Launcher for Rational ClearQuest. After authenticating, users can access the configured folders and reports on the report file server. This example creates the security role AuthenticatedUsers that includes all authenticated users. Then, a security constraint gives Report Launcher access to all users in the AuthenticatedUsers role.

<security-constraint>
   <web-resource-collection>
      <web-resource-name>authenticated</web-resource-name>
      <url-pattern>/*</url-pattern>
   </web-resource-collection>
   
   <auth-constraint>
      <role-name>AuthenticatedUsers</role-name>
   </auth-constraint>
   
   <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
   </user-data-constraint>
</security-constraint>

<login-config>
   <auth-method>FORM</auth-method>
   <realm-name>default</realm-name>
   <form-login-config>
      <form-login-page>/Login.jsp</form-login-page>
      <form-error-page>/Login.jsp?error=true</form-error-page>
   </form-login-config>
</login-config>

<security-role>
   <role-name>AuthenticatedUsers</role-name>
</security-role>

Example 2: Restrict access to the ManagementReports folder to department managers only

This code sample builds on the previous example. The bolded section of code establishes an additional Managers role as a subset of the AuthenticatedUsers role. This code creates a security constraint which restricts access to the /reports/home/ManagementReports folder to users with the Managers role. When unauthorized user clicks the ManagementReports folder link, the Report Launcher disables the link and decorates the folder entry with a lock. The lock indicates that the folder content is secure and cannot be accessed.

<security-constraint>
   <web-resource-collection>
      <web-resource-name>authenticated</web-resource-name>
      <url-pattern>/*</url-pattern>
   </web-resource-collection>
   
   <auth-constraint>
      <role-name>AuthenticatedUsers</role-name>
   </auth-constraint>

   <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
   </user-data-constraint>
</security-constraint>

<security-constraint>
   <web-resource-collection>
      <web-resource-name>secure</web-resource-name>
      <url-pattern>/reports/home/ManagementReports/*</url-pattern>
   </web-resource-collection>
   
   <auth-constraint>
      <role-name>Managers</role-name>
   </auth-constraint>
   
   <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
   </user-data-constraint>
</security-constraint>

<login-config>
   <auth-method>FORM</auth-method>
   <realm-name>default</realm-name>
   <form-login-config>
      <form-login-page>/Login.jsp</form-login-page>
      <form-error-page>/Login.jsp?error=true</form-error-page>
   </form-login-config>
</login-config>

<security-role>
   <role-name>AuthenticatedUsers</role-name>
</security-role>

<security-role>
   <role-name>Managers</role-name>
</security-role>