Secure InfoCenter Help

Introduction

The Eclipse InfoCenter provides a common framework allowing help and information documentation from different sources to be integrated. The Standalone Infocenter in turn allows these documentation content available on the intranet/internet for convenient access.

Prior to Eclipse 3.1, no security or access control mechanisms are provided for the InfoCenter content, making it unsuitable for serving up confidential information in an enterprise environment.

Eclipse 3.1 has been enhanced to allow secure access to the InfoCenter.

Enabling Secure Access to InfoCenter Help

By default, security and access control is turned off. To turn on secure access for the InfoCenter, follow the following steps.

1. Implement the IRealmFactory interface.
2. Enable the SSL connector in the help subsystem appserver.
3. Enable and configure the security constraint in the help web application.

Implement the IRealmFactory interface

To enable access control to the InfoCenter, one needs to create a plugin that implements the org.eclipse.tomcat.realmfactory extension point.

   <extension
         id="org.eclipse.test.simplerealm"
         name="%simplerealm.realm"
         point="org.eclipse.tomcat.realmfactory">
      <realmfactory class="org.eclipse.test.simplerealm.SimpleRealmFactory">
         <parameter
               name="userDefinitionFile"
               value="c:\\tomcat-users.xml"/>
      </realmfactory>
   </extension>

The extension point implemention declares a class that implements the IRealmFactory interface. In the example shown here, the class is called org.eclipse.test.simplerealm.SimpleRealmFactory.

The main purpose of classes implementing the IRealmFactory interface is to return an appropriate org.apache.catalina.Realm object, perhaps taking info account the configuration information provided in the extension point. A very simple implementation might look like the following

	/* (non-Javadoc)
	 * @see org.eclipse.core.runtime.IExecutableExtension#setInitializationData(org.eclipse.core.runtime.IConfigurationElement, java.lang.String, java.lang.Object)
	 */
	public void setInitializationData(IConfigurationElement config,
			String propertyName, Object data) throws CoreException {
		this.config = config;
		parameters = (Map) data;
	}
	
	/**
	 * Creates a realm appropriate for authenticating
	 * using the path specified in the userDefFile parameter.
	 * 
	 * @see org.eclipse.tomcat.extensions.IRealmFactory#createRealm(org.eclipse.tomcat.extensions.ConfigurationInfo[])
	 */
	public Realm createRealm() {
		MemoryRealm retVal = new MemoryRealm();
		IConfigurationElement [] parameters = config.getChildren();
		String filepath = null;
		for (int i =0; i < parameters.length; i++) {
			if ("userDefinitionFile".equals(parameters[i].getAttribute("name"))) {
				filepath = parameters[i].getAttribute("value");
				break;
			}
		}
		if (filepath != null) {
			retVal.setPathname(filepath);			
		}
		return retVal;
	}

How to implement a custom Realm object that could provide more sophisticated authentication (perhaps by going to a JNDI directory) is beyond the scope of this document. Please refer to the appropriate documentation on Tomcat for more information.

Enable the SSL connector in the help subsystem appserver

Before one can enable SSL for the help subsystem, one must create the Java key store file using the keytool command in the Java JDK. To create a new key store file containing a self signed certificate on windows,

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

Optionally, one could also set up an officially approved certificate. For more details on requesting and importing a Certificate from a Certificate Authority, see SSL Configuration How-to on the Tomcat site.

After the Java key store has been properly initialized, enable SSL for the help subsystem by editing the preferences.ini file in the plugin org.eclipse.tomcat. Modify the value of sslPort

# The port number to use for the SSL Connector
# Should consider moving this to the AppserverPlugin
sslPort = -1

Enable and configure the security constraint in the help web application

To enable the security constraint, uncomment the following section in the web.xml file in the plugin org.eclipse.help.webapp, under the directory WEB-INF.

<!-- Uncomment to enable secure access to the InfoCenter.
     ** Update the role-name s as appropriate.
	<security-constraint>
		<web-resource-collection>
			<web-resource-name>helproot</web-resource-name>
			<description></description>
			<url-pattern>/*</url-pattern>
			<http-method>
			GET</http-method>
			<http-method>
			PUT</http-method>
		</web-resource-collection>
		<auth-constraint>
			<description></description>
			<role-name>tomcat</role-name>
		</auth-constraint>
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
	</security-constraint>
	<login-config>
		<auth-method>BASIC</auth-method>
	</login-config>
	<security-role>
		<description></description>
		<role-name>tomcat</role-name>
	</security-role>
-->

How to start or stop infocenter from command line

The org.eclipse.help.standalone.Infocenter class has a main method that you can use to launch infocenter from a command line. The command line arguments syntax is:

-command start | shutdown | [-eclipsehome eclipseInstallPath] [-host helpServerHost] [-locales localeList] [-port helpServerPort] [-adminId administratorUserId] [-adminPassword administratorPassword] [-trustStoreLocation trustStoreLocation] [-trustStorePassword trustStorePassword] [-dir rtl] [-noexec] [platform options] [-vmargs JavaVMarguments]

To start an infocenter on port 8081 issue a start command by running

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_3.1.0.jar org.eclipse.help.standalone.Infocenter -command start -eclipsehome d:\myApp\eclipse -port 8081

To shut the infocenter down issue a shutdown command by running

java -classpath d:\myApp\eclipse\plugins\org.eclipse.help.base_3.1.0.jar org.eclipse.help.standalone.Infocenter -command shutdown -adminId adminUserId -adminPassword adminPassword -trustStoreLocation trustStoreLocation -trustStorePassword trustStorePassword -eclipsehome d:\myApp\eclipse

The options adminId, adminPassword, trustStoreLocation, and trustStorePassword are needed if secure access to the infocenter is enabled. The administrator must be authorized by the realm for accessing the Infocenter. The trust store options may be needed if the keystore is not an officially approved certificate.