The Grouper API requires:
- 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.
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.
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:
Then, in tomcat's server.xml, ensure that the Connector element for port 8009 is uncommented and contains directives similar to these:
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.
- 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:
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.
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
Grouper UI documentation
Java source for Grouper UI
Directory containing the as-built and customized UI servlet
Images and styles for the UI
Taglibs and other structural definitions
top level of Web Services package
Grouper WS servlet
Grouper WS documentation
Third party .jar files required by Grouper WS
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.