Configuring the Grouper API as of v1.3.1
In this section we describe all of the Grouper API configuration files and important settings.
The Grouper API is distributed with example configuration files with ".example" inserted in the middle of their names. These should be renamed or copied to remove the ".example" substring.
integrating the Grouper API with the database that will house your Groups Registry
integrating the Grouper API with chosen identity sources
defaults for Grouper privileges, enabling identified external users to act with elevated root-like privilege, changing the display name for internal subjects
Database-Related Settings and Procedures
Grouper uses Hibernate to persist objects in the Groups Registry, so all of the database-specific settings are located in grouper/conf/grouper.hibernate.properties. After modifying the default properties as needed, Grouper API ant tasks detailed below are used to create and install the Groups Registry schema and initialize the database.
Database Driver Location
Place the jar file containing the JDBC driver for your database in the grouper/lib/ folder. The Grouper v1.3.1 package includes the JDBC driver for HSQLDB v22.214.171.124 in this folder. You should replace it if you will be using a different version of HSQLDB.
General Property Settings
The grouper/conf/grouper.hibernate.properties file included in the Grouper API distribution contains sections pre-populated for HSQLDB, Postgresql, and Oracle. If you're using one of these, some of your configuration effort is just adding and removing comment characters. For others, it may be necessary to refer to more detailed Hibernate Configuration Information.
The basic properties that must be set are:
JDBC driver classname
JDBC URL for the database
database user's password
and one that probably ought to be set is:
classname of a Hibernate dialect, for setting platform specific features. Choices are listed here.
You may need to get a database support person to tell you what the values of these parameters must be for the instance of the database being configured.
Database-Specific Property Settings
In this section, we collect database-specific settings that we've become aware of. If your database technology is listed here, you may wish to follow the specific instructions for that technology.
Oracle 9i and Grouper API v1.2.1 and earlier - Prior to v1.3.0 Grouper used Apache DBCP for JDBC connection pooling and enabled prepared statement pooling by default. Prepared statement pooling must be disabled for Oracle 9i with the setting:
The operations in ant (or straight from Java) which affect the DB negatively (e.g. dropping and recreating the schema/data during unit tests) will generate a prompt to the user showing the database which will be affected, and confirming that it is ok. This prompt might get annoying or might not work correctly, so in the grouper.properties you can allow or deny db url/schema combinations. Here is documentation from grouper.example.properties:
Database Initialization Procedure
After setting Hibernate properties for your database, change your command shell to the grouper directory and execute the following two ant tasks to install the appropriate Groups Registry DDL and perform necessary initialization:
ant schemaexport - Generates DDL appropriate for your configured RDBMS and installs the tables.
ant db.init - Populates various tables with required logical schema information (the default set of group types and fields) and creates the root naming stem of the Groups Registry in the configured database.
If you've performed the junit testing using your production database, or for any other reason need to return the Groups Registry to its initial pristine state, do
ant db.reset - Cleans up the database, returning it to its just-initialized state.
Configuration of Source Adapters
Grouper uses Subject API compliant "source adapters" to integrate with external identity stores. "Subjects" are the objects housed there that are presented to Grouper for management vis-à-vis group membership and Grouper privileges. These may represent people, other groups, computers, applications, services, most anything for which you manage identity. With the exception of Grouper groups, Grouper treats all subjects opaquely. See the Subject API documentation for further background and details concerning subjects, source adapters, and other aspects of the Subject API.
Each source adapter connects with a single back-end store using JDBC or JNDI. Grouper makes no specific assumptions about the schema of any subject types. Instead, sections of the configuration file, grouper/conf/sources.xml, declare the details of how to connect with each back-end store, the identifier(s) to be used for the subjects it contains, how to select and search for subjects, and which subject attributes should be made available to Grouper.
Grouper v1.3.0 relies on v0.3.1 of the Subject API. Please refer to the section on Subject API v0.3.1 for detailed configuration information.
Three source adapter classes are included in the Grouper API v1.3.0 package. JDBCSourceAdapter and JNDISourceAdapter classes are included in subject-0.3.1.jar, and GrouperSourceAdapter is built along with the Grouper API. Every Grouper API deployment MUST include a*source* element in grouper/conf/sources.xml for the GrouperSourceAdapter so that Grouper can refer to its own groups in the same manner as other subjects.
Choosing Identifiers for Subjects
Identifiers and their management can get complicated. They can be revoked or not, re-assigned or not, lucent or opaque, etc. Depending on such characteristics, a given identifier might be a good or bad choice to use in the context of managing the identified subject's group memberships.
For example, a username is often lucent - easily remembered by the person to whom it is associated. But it may also be revokable, meaning that it no longer refers to that person (perhaps they have a new one), or even re-assignable, meaning that it might refer to some other person at a later time. If a username is used to record membership, username changes must trigger corresponding membership changes. A username is better suited to authentication than it is to indicating membership.
On the other hand, an opaque registryID (machine, not human, readable) that never changes is great for membership, but lousy for authentication - it might not even be known by the person to whom it is associated. How would I identify myself to Grouper if I wished to opt-in to a list or manage a group?
Grouper accommodates subject identifier issues in two ways. First, it maintains UUIDs for every subject and group within the Groups Registry. These are never exposed by the API, but are associated with externally supplied subject identifiers within the Groups Registry. This approach allows the identifier associated with a given subject to be changed without any need to change actual memberships.
Second, by relying on the Subject API, Grouper is able to lookup subjects that are presented with an identifier in one namespace and obtain identifiers in other namespaces for that subject. That means that it can translate a username into a registryID, for example. So, when a user authenticates to an application using the Grouper API, that application can use the Subject API to fetch an identifier for the person chosen by the site for use in memberships. Similarly, when a membership in the Groups Registry is to be expressed elsewhere, the identifier used for group members can be translated by a provisioning connector by use of the Subject API into one that is suitable in the provisioned context.
All configuration of Grouper privileges detailed in this section occur in the grouper/conf/grouper.properties file.
Grouper requires that all subjects must be explicitly granted access or naming privileges (cf. Glossary), with one caveat. There is a special "subject" internal to Grouper called the ALL subject, which is a stand-in for any subject. The ALL subject can be granted a privilege in lieu of assigning that privilege explicitly to each and every subject.
When a new group or naming stem is created, any of its associated privileges can be granted by default to the ALL subject. This is configured by a series of properties in grouper.properties, one per privilege. If a property has the value "true" then ALL is granted that privilege by default when a group or naming stem is created. Otherwise it is not, and hence no subject has that privilege by default.
Value in Grouper v1.3.1 Distribution
Grouper has another special "subject" called GrouperSystem that acts as a super-user. GrouperSystem is permitted to do everything - the privilege system is ignored for that special subject. Grouper can be configured to consider all members of a distinguished group to be able to act as super-users, much as the "wheel" group does in BSD Unix. Two properties control this behavior:
"true" or "false" to enable or disable this capability.
The group name of the group whose members are to be considered security-equivalent to GrouperSystem.
The Grouper UI enables users that belong to the wheel group to choose when to act with the privileges of GrouperSystem and when to act as their normal selves.
Changing the display name of GrouperAll and GrouperSystem
As of version 1.3.0 the Grouper UI started referring to GrouperAll as EveryEntity and GrouperSystem as GrouperSysAdmin. As of version 1.3.1 the name attribute of GrouperAll and GrouperSystem can be set through the properties below.
The name to use for GrouperAll instead of EveryEntity
The name to use for GrouperSystem instead of GrouperSysAdmin
If you choose not to use the defaults you will have to update the UI nav.properties file to ensure consistency e.g. subject.privileges.from-grouperall=inherits from EveryEntity
Changing default privilege caching
Grouper includes three `PrivilegeCache` implementations:
- NoCachePrivilegeCache - No caching performed
- SimplePrivilegeCache - Caches results but flushes all cached entries upon any update
- SimpleWheelPrivilegeCache - Same as 'SimplePrivilegeCache' but with better support for using a wheel group.
The privileges.access.cache.interface and privileges.naming.cache.interface properties can be set to determine the privilege caching regimen. The default is edu.internet2.middleware.grouper.NoCachePrivilegeCache.
Using a privilege management system external to Grouper
Grouper's internal security implementation relies on two java interfaces, one for Naming Privileges and another for Access Privileges. Grouper ships with classes that implement these interfaces, but 3rd parties are free to supply their own and so manage Grouper privileges using a privilege management system external to Grouper. Two properties declare the java classes that Grouper will use to implement these interfaces:
classname of the java class that implements the Access Interface
classname of the java class that implements the Naming Interface
Note: although we've provided the can and the dish, we haven't as yet eaten our own dogfood!
Logging is configured in the grouper/conf/log4j.properties configuration file. By default Grouper will write event log information to grouper/grouper_event.log, error logging to grouper/grouper-error.log, and debug logging, if enabled, to grouper/grouper-debug.log. The log4j configuration can be adjusted to control the verbosity, type and output of Grouper's logging.
In addition, there are several configuration parameters in grouper/conf/grouper.properties that may be adjusted to control the logging of effective membership modifications in the event log.
Questions or comments? Contact us|Contact Information|Contact Information\.