Skip to end of metadata
Go to start of metadata

Prerequisites

The Grouper API requires:

  • Java
  • database (e.g. MySQL, Oracle, PostgreSQL, etc.)

The Grouper UI and WS packages also require:

The Grouper Product Specsheet provides additional details regarding requirement specifications.

The #Project Layout describes the directory structure of Grouper packages.

Relational Database

Grouper uses Hibernate to persist objects in a relational database, called the Groups Registry. Hibernate in turn uses JDBC for database connectivity. The .jar file containing the JDBC driver for the RDBMS of your choice must be available during installation.

All of Grouper's access to the underlying database is by means of a single account. The username and password or other authentication token for this account must also be available during installation.

The Grouper distribution includes the free and open source HSQLDB relational database, which is used in conjunction with testing the compiled code.

Web Server

Although it is possible to run Grouper without a web server, it is likely needed for a production deployment. The web server will restrict access to the Grouper application, authenticate your users, optionally authenticate the special GrouperSystem account, and implement SSL.

If you will use Apache v2.2+, configure apache to load mod_proxy and mod_proxy_ajp and include configuration directives similar to the following:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
ProxyRequests Off

Then, in tomcat's server.xml, ensure that the Connector element for port 8009 is uncommented and contains directives similar to these:

<Connector port="8009"
    enableLookups="false" redirectPort="8443" protocol="AJP/1.3"
    tomcatAuthentication="false"/>

If you will use Apache v1.3 or v2.0.X, configure apache to load the mod_jk connector. The following configuration directs Apache to use mod_jk to redirect queries for Grouper to Tomcat. This may be done by including the following text directly in httpd.conf, or making a separate file and including it in httpd.conf.

<IfModule \!mod_jk.c>
  LoadModule jk_module libexec/mod_jk.so
</IfModule>
JkWorkersFile "/usr/local/tomcat/conf/jk/workers.properties"
JkLogFile "/usr/local/apache/logs/mod_jk.log"
JkLogLevel emerg JkMount /grouper/* ajp13
  • Add address="127.0.0.1" to Tomcat's server.xml inside the <Ajp13Connector> configuration element to prevent off-host access.
    • For Tomcat 5.5 or newer, add request.tomcatAuthentication="false" to the <Ajp13Connector> configuration element in server.xml to ensure that the user's identity is passed from Apache to the servlet environment.
    • For Tomcat 5.0.x or older, add tomcatAuthentication="false" to the <Ajp13Connector> configuration element in server.xml to ensure that the user's identity is passed from Apache to the servlet environment.
    • Tomcat 4.1.x defaults to having the Coyote connector enabled in /conf/server.xml. This fails with mod_jk and must be commented out. Then, uncomment and modify the traditional AJP 1.3 connector as indicated above.
  • The AJP13Connector for tomcat is not compatible with the new JMX support. To remove some warnings that will appear in the Tomcat log every time Tomcat is restarted, comment out all of the JMX stuff (anything that says "mbeans") from server.xml.

Apache-based User Authentication

The interaction between the Grouper UI and an Apache-based local authentication system is implemented by providing the UI with the identity of the browser user through REMOTE_USER. Any authentication system that is capable of protecting a block of webspace using httpd.conf and populating the REMOTE_USER header variable is compatible with Grouper. This associates the appropriate authentication mechanism with the URL of the Grouper servlet, ensuring users authenticate and that their login name is passed to Grouper. The following example demonstrates use of a very basic authentication method with the Grouper UI:

<Location /grouper>
  SSLRequireSSL
  AuthType Basic
  AuthName "ExampleU Login Service"
  require valid-user
  ProxyPass ajp://localhost:8009/grouper/
 </Location>

Note that the ProxyPass declaration is included only when using mod_proxy_ajp.

Grouper UI-integrated User Authentication

The Grouper UI optionally supports direct integration of external authentication systems with the UI servlet. If this style of providing external authentication services to Grouper is chosen, REMOTE_USER and use of Apache-based user authentication is not needed. See How to Customize Authentication in the Grouper UI.

Grouper Web Service Authentication

Grouper Web Services can be protected by

  • REMOTE_USER provided by the servlet container it runs in,
  • Apache Rampart for WS-Security style of access protection, or
  • a custom authentication plug-in.

See Authentication for Grouper Web Services for details.

Project Layout

The Grouper API, UI, and WS packages must be unpacked under the same parent directory in order to install successfully. The parent directory must be writable because the Grouper UI build process will attempt to create a build directory under the parent directory.

The directory structure of the unpacked distributions is:

grouper/

top level of API package

conf/

Configuration files for Grouper and third party components

bin/

Grouper command line utilities

dist/

Compiled code, javadoc, and other generated artifacts

lib/

Third party .jar files required by the Grouper API

logs/

Default location for log files

misc/

Currently holds stub instructions for the binary distribution builder

src/

Java source for Grouper API and API test suite

LICENSE

License under which Grouper may be used

build.xml

Ant configuration file

grouper-ui/

top level of UI package

conf/

UI properties files and other resources

contrib/

Contributed software

doc/

Grouper UI documentation

java/

Java source for Grouper UI

webapp/

Directory containing the as-built and customized UI servlet

webapp/grouper

Images and styles for the UI

webapp/i2mi

Generic styles

webapp/WEB-INF

Taglibs and other structural definitions

grouper-ws/

top level of Web Services package

grouper-ws/grouper-ws/

Grouper WS servlet

grouper-ws/grouper-ws/build/

Compiled code

grouper-ws/grouper-ws/conf/

Configuration files

grouper-ws/grouper-ws/doc/

Grouper WS documentation

grouper-ws/grouper-ws/lib/

Third party .jar files required by Grouper WS

grouper-ws/grouper-ws/webapp/

Servlet files

grouper-ws/grouper-ws/webservices/

Apache .aar files

grouper-ws/grouper-ws-java-generated-client/

Sample Axis-generated client

grouper-ws/grouper-ws-java-manual-client/

Sample "Lite" client

grouper-ws/grouper-ws-test/

used for testing

Note: The file grouper/lib/README lists the third party software used by Grouper and identifies the version, source, and license for each.

See Also

Grouper Product Specs


  • No labels