Skip to end of metadata
Go to start of metadata


The Grouper API requires:

  • Java 8
  • 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.

Review the Grouper TIER packaging requirements

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/
LoadModule proxy_ajp_module modules/
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"

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/
JkWorkersFile "/usr/local/tomcat/conf/jk/"
JkLogFile "/usr/local/apache/logs/mod_jk.log"
JkLogLevel emerg JkMount /grouper/* ajp13
  • Add address="" 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>
  AuthType Basic
  AuthName "ExampleU Login Service"
  require valid-user
  ProxyPass ajp://localhost:8009/grouper/

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:


top level of API package


Configuration files for Grouper and third party components


Grouper command line utilities


Compiled code, javadoc, and other generated artifacts


Third party .jar files required by the Grouper API


Default location for log files


Currently holds stub instructions for the binary distribution builder


Java source for Grouper API and API test suite


License under which Grouper may be used


Ant configuration file


top level of UI package


UI properties files and other resources


Contributed software


Grouper UI documentation


Java source for Grouper UI


Directory containing the as-built and customized UI servlet


Images and styles for the UI


Generic styles


Taglibs and other structural definitions


top level of Web Services package


Grouper WS servlet


Compiled code


Configuration files


Grouper WS documentation


Third party .jar files required by Grouper WS


Servlet files


Apache .aar files


Sample Axis-generated client


Sample "Lite" client


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