GROUPER:  About   FAQ   Software  Documentation   Contribute   WG   Contact

This is an archived document. For the current version, please see Configuring the Grouper API. Thanks!

Configuring the Grouper API v1.0

In this section we describe all of the Grouper API configuration files and important settings.

Section

Configuration File

Purpose

Database-Related Settings and Procedures

grouper.hibernate.properties

integrating the Grouper API with the database that will house your Groups Registry

Configuration of Source Adapters

sources.xml

integrating the Grouper API with chosen identity sources

Grouper Privileges

grouper.properties

defaults for Grouper privileges, enabling identified external users to act with elevated root-like privilege

Logging

log4j.properties, grouper.properties

logging

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.

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:

Property Name

Purpose

hibernate.connection.driver_class

JDBC driver classname

hibernate.connection.url

JDBC URL for the database

hibernate.connection.username

database user

hibernate.connection.password

database user's password

    and one that probably ought to be set is:

hibernate.dialect

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 -  Grouper uses Apache DBCP for JDBC connection pooling and enables prepared statement pooling by default. Prepared statement pooling must be disabled for Oracle 9i with the setting:

hibernate.dbcp.ps.maxIdle = 0

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 1.0 relies on v0.2.1 of the Subject API. Please refer to the section on Subject API v0.2.1 for detailed configuration information.

Three source adapter classes are included in the Grouper API 1.0 package. JDBCSourceAdapter and JNDISourceAdapter classes are included in subject-0.2.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.

Grouper Privileges

    All configuration of Grouper privileges detailed in this section occur in the grouper/conf/grouper.properties file.

Default privileges

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.

Property Name

Value in Grouper 1.0 Distribution

groups.create.grant.all.admin

                     false

groups.create.grant.all.optin

                     false

groups.create.grant.all.optout

                     false

groups.create.grant.all.update

                     false

groups.create.grant.all.read

                     true

groups.create.grant.all.view

                      true

stems.create.grant.all.create

                     false

stems.create.grant.all.stem

                     false

Super-user Privileges

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:

Property Name

Description

groups.wheel.use

"true" or "false" to enable or disable this capability.

groups.wheel.group

The group name of the group whose members are to be considered security-equivalent to GrouperSystem.

Note that, as of v1.0, 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.

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:

Property Name

Description

privileges.access.interface

classname of the java class that implements the Access Interface

privileges.naming.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

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.

# Control whether the addition and deletion of effective groups memberships
# are logged in the event log.  If using the _GrouperAccessAdapter_ this
# will include granted and revoked access privileges.
memberships.log.group.effective.add   = true
memberships.log.group.effective.del   = true

# If using _GrouperNamingAdapter_, control whether the granting and
# revoking of effective naming privileges are logged in the event log.
memberships.log.stem.effective.add    = true
memberships.log.stem.effective.del    = true

     (question) Questions or comments? (info) Contact us.

GROUPER:  About   FAQ   Software  Documentation   Contribute   WG   Contact