Securing the Server  

Secure the GenePattern server to control who has access to which operations. Since GenePattern is primarily a web application (including SOAP interfaces) running on a web server, general approaches for securing web servers are applicable to the GenePattern server. In addition, GenePattern provides several security features that can easily be used by non-technical users to control access to the server.

This section describes several ways to secure the GenePattern server:

• Access Filtering
• Password Protection
• User Accounts
• User Permissions
• User Authentication and Authorization
• Secure Sockets Layer (SSL) Support

Access Filtering

Use the Access page to define which GenePattern clients have access to the GenePattern server. This is the simplest way to secure your GenePattern server.

Access filtering prevents users from connecting to the GenePattern server unless they come from a known computer. If your computer cannot access the server, you cannot access the server regardless of your username/password or permissions. The localhost (127.0.0.1) computer cannot be denied access to the locally installed GenePattern server. This prevents you from inadvertently denying yourself access to the server.

To use access filtering (as described in Modifying Server Settings):

1. Click Administration>Server Settings.
2. Use the Access page to determine which clients have access to your GenePattern server:

   

   • Click Standalone to allow only local clients to connect to the server; that is, you can access this GenePattern server only from the computer that it is running on.
   • Click Any Computer (default) to allow any client to connect to the server.
   • Click These Domains to allow only clients from specific domains to connect to the server. Enter a comma-separated list of domains or IP addresses in the text box, for example: broadinstitute.org,dfci.harvard.edu,mit.edu.
     GenePattern scans all incoming connection attempts. If they match in whole or in part any domain name or IP address in this list, the server allows access; otherwise, the server redirects the connection to a page indicating that the server does not allow access.

Password Protection

By default, the GenePattern server requires only a user name to authenticate a GenePattern user. You can easily add password protection by modifying the GenePattern server properties.

To add password protection, modify the GenePattern server properties:

1. Edit the GenePattern configuration file, GenePatternServer/resources/genepattern.properties.
2. Set the requirePassword property to true: requirePassword=true.
3. Save the genepattern.properties file.
4. Restart the GenePattern server.

When you add password protection to the server:

• Existing users are assigned a blank password. The first time a user signs in with a blank password, the GenePattern server requires the user to set the password.
• New users are required to register before using the GenePattern server. By registering, the user creates a GenePattern account with an associated username, password, and email address.
• The sign-in screen prompts you for a username and password. If you forget your password, click the Forgot your password? link and GenePattern emails you a temporary password.

Assigning passwords to existing user accounts prevents anyone from inadvertently or intentionally logging into and taking control of another user’s account. After adding password protection to the server, set passwords for existing users as follows:

1. Select Administration>Server Settings>Users and Groups to list all users registered on the server.
2. Sign into GenePattern using the name of an existing user.
3. When GenePattern prompts you to set a password, select a password for that user.
4. After setting the password, GenePattern displays the Change Email page (My Settings). Set the user’s email address if it has not been set. This is the address GenePattern uses to send the user a new password if necessary.
5. Sign out and repeat the process for the next user.
6. After setting passwords for all users, let them know that passwords have been set. You do not need to send the users their passwords. Simply ask users to sign into GenePattern and click the Forgot your password? link to have GenePattern send a temporary password.

User Accounts

By default, users create their own accounts by clicking the Registration link on the GenePattern login page. To configure GenePattern to allow only administrators to create new accounts:

1. Shut down the server.
2. Edit the file GenePatternServer/Tomcat/webapps/gp/WEB-INF/web.xml. Remove registerUser.jsf from the no.login.required.redirect.to.home parameter value. After the edits, it looks like this:
   

   <init-param> <!-- List of jsf pages that user can access if not logged in. If user requests one of these pages while logged in, he is redirected to the home page. --> <param-name>no.login.required.redirect.to.home</param-name> <param-value>login.jsf,forgotPassword.jsf</param-value> </init-param>

   Result: A user cannot access the registration page until she has successfully logged into the server.
3. Edit the file GenePatternServer/resources/actionPermissionMap.xml. Add the following line to the <actionPermissionMap>:
   

   <url link="registerUser.jsf" permission="adminServer"/>

   Result: A user must be an administrator to access the registration page.
4. Edit the file GenePatternServer/Tomcat/webapps/gp/pages/login.xhtml. Replace the phrase
   

   rendered="#{loginBean.createAccountAllowed and loginBean.showRegistrationLink}">

   with
   

   rendered="false">

   Result: Removes the Click to register link from the login page.
5. Restart the server.

To create an account:

1. Login using an administrator account. GenePattern displays the home page.
2. Open the user registration page, registerUser.jsf. For example, if the URL for the GenePattern home page is
   

   http://127.0.0.1:8080/gp/pages/index.jsf

   change the URL to
   

   http://127.0.0.1:8080/gp/pages/registerUser.jsf

3. Create the new user account. You are automatically logged in as that new user.
4. To create another new account, logout of the new user account and login using your administrator account.

User Permissions

User permissions determine valid actions for the user. Permissions are based on two configuration files in the GenePatternServer/resources directory (the links show the default files):

• userGroups.xml defines user groups, as described in Creating Groups and Administrators
• permissionMap.xml defines which user groups have which permissions

A user who belongs to multiple groups is given the most permissive permissions granted to those groups. For example, an administrator who belongs to other groups retains administrator permissions.

To assign or modify user permissions, edit the permissionMap.xml file. The XML syntax is simple but must be followed carefully. The rules are as follows:

• To assign permissions to a group, add a <group> element to that permission. A <permission> element may have any number of <group> elements. A <group> element may be listed under any number of <permission> elements.
• To assign a permission to all groups (and therefore all users), use the syntax <group name="*"/>.The presence of a group named * means that all groups (and therefore all users) have that permission.
• Warning: Do not add or remove <permission> elements. GenePattern uses them to define the permissions that it requires and implements. The permissions are described in the following table.

By default:

• When you install GenePattern, all groups have the following permissions: createPrivatePipeline, createPublicPipeline, createPrivateSuite, createPublicSuite. Administrators have all permissions.
• On the GenePattern public server, all groups have the following permissions: createPrivatePipeline, createPrivateSuite. Administrators (the GenePattern team) have all permissions.

User Authentication and Authorization

You can configure the GenePattern server to provide password protection, restrict creation of user accounts, and assign permissions based on groups. Additional or alternative authentication and authorization mechanisms can be added to the server by an administrator with programming experience. The remainder of this section is written for such a programmer. Note: The links in this section display the source code for the default GenePattern installation, which should be used as the starting point for any modifications.

Authentication

The authentication filter, AuthenticationFilter.java, controls whether a user can log into the server (typically based on username and password). The easiest way to modify GenePattern authentication is by implementing the IAuthenticationPlugin.java interface:

1. Implement the IAuthenticationPlugin interface. Use the IAuthenticationPlugin.java file as the starting point. Comments in the file provide the specification. For example, create a MyCustomGenePatternAuthentication.java interface.
2. Compile the interface and add it to the classpath for the GenePattern server web application.
3. Modify the authentication.class property in the GenePattern configuration file, GenePatternServer/resources/genepattern.properties, to point to the new interface. For example:
   authentication.class=org.genepattern.server.auth.MyCustomGenePatternAuthentication
4. Restart the GenePattern server for the changes to take effect.

See ftp://ftp.broadinstitute.org/pub/genepattern/src/gp-custom-auth.zip for an example project that prepares a custom authentication jar file for deployment to your local GenePattern server.

If the IAuthenticationPlugin interface methods do not provide enough flexibility, you can modify the authentication filter.

Authorization

The authorization filter, AuthorizationFilter.java, controls which GenePattern operations (web pages) the user can access. As described in User Permissions, permissions are based on two configuration files: userGroups.xml, which defines user groups, and permissionMap.xml, which defines which groups have access to which permissions.

Organizations that have user groups defined in an external system can use those groups rather than using the userGroups.xml. To have the authorization filter use external user groups rather than the userGroups.xml file, implement the IGroupMembershipPlugin.java interface:

1. Implement the IGroupMembershipPlugin interface. Use the IGroupMembershipPlugin.java file as the starting point. Comments in the file provide the specification. For example, create a MyCustomGroupMembershipPlugin.java interface.
2. Compile the interface and add it to the classpath for the GenePattern server web application.
3. Modify the group.membership.class property in the GenePattern configuration file, GenePatternServer/resources/genepattern.properties, to point to the new interface. For example:
   group.membership.class=org.genepattern.server.auth.MyCustomGroupMembershipPlugin
4. Restart the GenePattern server for the changes to take effect.

To assign permissions to a group authorized through the IGroupMembershipPlugin interface, include the group in the permissionMap.xml file. If the IGroupMembershipPlugin interface methods do not provide enough flexibility, you can modify the authorization filter.

Modifying the filters

The authentication and authorization filters are servlet filters installed in front of the GenePattern web application in the GenePatternServer/Tomcat/webapps/gp/WEB-INF/web.xml file. To implement an alternative authentication (or authorization) filter:

1. Write and compile a new ServletFilter that that performs the desired authentication (or authorization).
2. Place the jar file containing the new ServletFilter into the following directory:
   */GenePatternServer/Tomcat/webapps/gp/WEB-INF/lib
3. Modify the GenePattern server’s web.xml document.
   */GenePatternServer/Tomcat/webapps/gp/WEB-INF/web.xml
   Note: It is important to maintain the existing order of the servlet filters in the web.xml document as they are used in the order they are defined in the document. The Authentication filter must come before the Authorization filter for the Authorization filter to work.
4. Change the definition of the AuthenticationFilter (or AuthorizationFilter) to use the class that you have provided.
5. Add any necessary configuration elements that it requires.
6. Restart the GenePattern server for the changes to take effect.

Note: If you look at the code for the default Authentication Filter (AuthenticationFilter.java), you will see that it allows requests through that have a parameter called jsp_precompile that have come from the localhost. If you do not allow these requests through unauthenticated, you will see a series of errors when you start the GenePattern server as it attempts to precompile the JSP pages. These are not fatal errors, but they slow down server response for users the first time that pages are accessed following a server restart.

Secure Sockets Layer (SSL) Support

This section describes how you can modify the GenePattern web application to run on a web server that is configured to use the HTTPS protocol, where essentially the regular http requests are routed through a secure sockets layer (SSL) making them much harder for hackers to access. If you have installed your GenePattern server onto a web server other than the default Tomcat instance it is distributed with, configure your web server according to its instructions and then follow Step 2 below.

Note: When running under SSL, programming language clients and the GenePattern web client may not be able to connect to your GenePattern server.

Step 1. Configure Tomcat for SSL support

Follow the instructions available at http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html to configure the Tomcat instance for using SSL. In doing so, you will modify the Tomcat configuration file, which is located in the GenePatternServer/Tomcat/conf directory.

Step 2.Configure GenePattern for SSL

Once the Tomcat (or other web server) has been configured for SSL, modify the GenePattern configuration file, GenePatternServer/resources/genepattern.properties, to ensure that its properties are in synch with the web server:

1. Add a new key, java.net.ssl.trustStore=<path to keystore>.
   This should point to the keystore you created when configuring Tomcat (above) or some keystore that GenePattern can use to establish SSL connections.
2. Modify the value for the key GENEPATTERN_PORT to use the https port you selected when configuring Tomcat (above).
3. Modify the value for the key GenePatternURL to use the https protocol and the https port you selected, for example:
   http://localhost:8080/gp becomes https://localhost:8443/gp

Save the genepattern.properties file and restart your server. Any bookmarked links to your GenePattern server must be updated to the new protocol and port.

<< Using a Queuing System | Up | Changing the GenePattern Database (HSQL to Oracle) >>