Grouper Install - Configure - Populate -- Fall 2013 corrections

Overview and Assumptions: Security of Grouper Data

These instructions assume that the Grouper instance backing BSP services is a stand-alone instance that is not used for other purposes. This assumption is fundamental to the approach employed to secure Grouper data.

[Note that Grouper-backed BSP functionality includes the Group Service (cf. Grouper Install - Configure - Populate -- Fall 2013 corrections) and data on known and trusted BSP clients (cf. Grouper Install - Configure - Populate -- Fall 2013 corrections).]

Grouper data is secured by radically limiting the number of logins (Grouper users) enabled in the Grouper instance. In the base configuration there are only four users plus the default user, GrouperSystem – a total of five sets of user id/password credentials – granted direct access to the Grouper application, API, and/or data. These users are described in the table below:

1. By configuration, ALL Grouper users have READ and VIEW access to all stems and groups. The proper functioning of BSP-hosted services that rely on this backing instance assume this configuration. (Cf. {GROUPER_HOME}/conf/grouper.properties, specifically the TRUE values set for groups.create.grant.all.read and groups.create.grant.all.view)
2. Assuming a secure installation on a secure server, only the Grouper users listed in the table above can access Grouper data
3. All end users – including subjects who create, administer, and are members of groups under the bamboo.groups stem -- access Grouper data solely via the BSP-hosted Group Service, which is implemented such that:
   
   1. The Group Service passes an end-user's subject identifier to Grouper in an ActAs parameter, enabling application of Grouper-enforced permissions per user
   2. The Group Service reads from and writes only to stems and groups under the bamboo:groups top-level stem
4. For data in the bamboo:projects and bamboo:admin stems:
   
   1. Only GROUPER_UI_ADMIN_USER1 (and optionally GROUPER_UI_ADMIN_USER2, GROUPER_UI_ADMIN_USER3, etc.) exercise write-access
   2. Write-access is performed within these stems via the Grouper UI
   3. The only access exercised by BSP Services via the Web Services API (as BSP-hosted IAM services are implemented in v0.9.0-ALPHA) is read-access using the BSP_READ_ONLY_SERVICE_USER id and corresponding password.

As a consequence of the assumptions enumerated above:

• User-created stems and groups in the bamboo:groups node can be READ and VIEWed by any authenticated Bamboo user via the BSP-hosted Group Service. These permissions cannot be revoked in a graceful, programmatic way given recommended configuration and service functionality.
• Permissions beyond READ and VIEW may be granted and revoked by end users who are stem and group creators (because they obtain ADMIN rights upon stem or group creation), and their delegates. Cf. Grouper Install - Configure - Populate -- Fall 2013 corrections.
• Only BSP-hosted utility services (unavailable to end-users) have read access to stems and groups under bamboo:projects or bamboo:admin.

Installation

Grouper Install

Command line (console) input and selected output

  
$ which psql 
/usr/bin/psql 
$ psql --version 
psql (PostgreSQL) 9.1.3 
contains support for command-line editing 
$ sudo su postgres 
[sudo] password for <USER>: 
bash-4.2$ psql 
Password: 
psql (9.1.3) 
Type "help" for help. 
  
postgres=# CREATE DATABASE grouperdb ENCODING 'UTF8'; 
CREATE DATABASE 
postgres=# CREATE user grouper with password 'grouper_password'; 
CREATE ROLE 
postgres=# GRANT ALL PRIVILEGES ON DATABASE grouperdb TO grouper; 
GRANT 
postgres-# \q 
bash-4.2$ exit 
exit 
$ which java 
/usr/java/default/bin/java 
$ java -version 
java version "1.6.0_32" 
Java(TM) SE Runtime Environment (build 1.6.0_32-b05) 
Java HotSpot(TM) 64-Bit Server VM (build 20.7-b02, mixed mode)

$ sudo bash
[sudo] password for <USER>:
[root@bsp-dev]# cd /var/tmp/download
[root@bsp-dev download]# wget http://www.internet2.edu/grouper/release/2.1.2/grouper.installer-2.1.2.tar.gz
(...)
[root@bsp-dev download]# tar xvf grouper.installer-2.1.2.tar.gz
grouper.installer-2.1.2/
grouper.installer-2.1.2/README.txt
grouper.installer-2.1.2/grouperInstaller.jar
[root@bsp-dev download]# cd /opt
[root@bsp-dev opt]# mkdir grouper-2.1.2
[root@bsp-dev opt]# ls -la
total 12
drwxr-xr-x  3 root root 4096 Sep  7 17:43 .
drwxr-xr-x 22 root root 4096 Aug 24 18:54 ..
drwxr-xr-x  2 root root 4096 Sep  7 17:43 grouper-2.1.2
[root@bsp-dev opt]# cd /var/tmp/download/grouper.installer-2.1.2/
[root@bsp-dev grouper.installer-2.1.2]# java -jar grouperInstaller.jar

Enter in the Grouper install directory (note: better if no spaces or special chars) [/var/tmp/download/grouper.installer-2.1.2]:  /opt/grouper-2.1.2 
 

Enter the default IP address for checking ports (just hit enter to accept the default unless on a machine with no network, might want to change to 127.0.0.1): [0.0.0.0]: [RETURN]

[...]

Do you want to set gsh script to executable (t|f)? [t]: [RETURN]

[...]

  
Do you want to run dos2unix on gsh.sh (t|f)? [t]:  f  [RETURN]
 

Do you want to use the default and included hsqldb database (t|f)? [t]:  f  [RETURN]
  
################################## 
  
Example mysql URL: jdbc:mysql://localhost:3306/grouper 
Example oracle URL: jdbc:oracle:thin:@server.school.edu:1521:sid 
Example hsqldb URL: jdbc:hsqldb:hsql://localhost:9001/grouper 
Example postgres URL: jdbc:postgresql://localhost:5432/database 
Example mssql URL: jdbc:sqlserver://localhost:3280;databaseName=grouper 
  
Enter the database URL [jdbc:hsqldb:hsql://localhost:9001/grouper]:  jdbc:postgresql://localhost:5432/grouperdb 
Note: you need to change the search sql in the jdbc source in the grouperApi/conf/sources.xml... the change is in the comments in that file 
 

  
Ready to continue? (t|f)? t  [RETURN] 
Database user [sa]:  grouper 
Database password (note, you aren't setting the pass here, you are using an existing pass, this will be echoed back) [<blank>]:  grouper_password 
 

[...]

  
Do you want to init the database (delete all existing grouper tables, add new ones) (t|f)?  t  [RETURN]
  
[...]
  
Do you want to add quickstart subjects to DB (t|f)? [t]: [RETURN]
 

[...]

Do you want to add quickstart data to registry (t|f)? [t]: [RETURN]

[...]

Do you want to start the Grouper loader (daemons)?

  (note, if it is already running, you need to stop it now, check ps -ef | grep gsh | grep loader) (t|f)? [f]: t [RETURN]

[...]

Do you want to set the tomcat memory limit (t|f)? [t]: [RETURN]

[...]

Do you want to set tomcat scripts to executable (t|f)? [t]: [RETURN]

[...]

Do you want to run dos2unix on tomcat sh files (t|f)? [t]: f [RETURN]

[...]

What ports do you want tomcat to run on (HTTP, JK, shutdown): [8080, 8009, 8005]: 8070, 8709, 8705 [RETURN]

[...]

Should we stop tomcat anyway? (t|f)? [f]: [RETURN]

[...]

Do you want to set the log dir of UI (t|f)? [t]: [RETURN]

[...]

Enter the UI log dir: [/opt/grouper-2.1.2/apache-tomcat-6.0.35/logs/grouperUi]: [RETURN]

[...]

Enter the URL path for the UI [grouper]: [RETURN]

[...]

Enter the GrouperSystem password:  BambooGrouperSystemPassword 
  
[...]

Do you want to set the GrouperSystem password in /opt/grouper-2.1.2/apache-tomcat-6.0.35/conf/tomcat-users.xml? [t]: [RETURN]

[...]

Should we stop tomcat anyway? (t|f)? [f]: [RETURN]

[...]

Should we check ports to see if tomcat was able to start (t|f)? [t]: [RETURN]

**** Cf. console output in red below. Note port, URL path *** 
 

##################################

Go here for the Grouper UI (change hostname if on different host):  http://localhost:8070/grouper/ 

##################################

Do you want to build the Grouper WS? (t|f) [t]: [RETURN]

[...]

Should we check ports to see if tomcat was able to stop (t|f)? [t]: [RETURN]

[...]

Do you want to set the log dir of WS (t|f)? [t]: [RETURN]

Enter the WS log dir: [/opt/grouper-2.1.2/apache-tomcat-6.0.35/logs/grouperWs]: [RETURN]

Enter the URL path for the WS [grouper-ws]: [RETURN]

[...]

Should we stop tomcat anyway? (t|f)? [f]: [RETURN]

[...]

Should we check ports to see if tomcat was able to start (t|f)? [t]: [RETURN]

Do you want to install the provisioning service provider (t|f)? [t]: f [RETURN]

[...]

**** Cf. console output in red below. Note port, URL path ***

This is the Grouper WS URL (change hostname if on different host):  http://localhost:8070/grouper-ws/

[root@bsp-dev grouper.installer-2.1.2]#

[CONFIGURE APACHE WEB SERVER BEFORE LOGGING IN, or the password for GrouperSystem will be exposed to network traffic-sniffing]

Browse to Grouper UI at https://bsp-dev.projectbamboo.org/grouper/ (substituting <your URL> for bsp-dev.projectbamboo.org after configuring Apache Web Server)

Configure Apache Web Server for secure Grouper access

• Assumes httpd is set up and SSL is enabled and configured as described in Grouper Install - Configure - Populate -- Fall 2013 corrections
• Assumes mod_proxy_ajp module is loaded by Apache Web Server (httpd) [e.g., LoadModule proxy_ajp_module modules/mod_proxy_ajp.so]
• The goal of the following installations steps is to enable and require https:// access, by:
  • assuring that port 8070 is NOT open in the Grouper host's firewall
  • adding appropriate directives to the Apache web server's (httpd) ssl.conf file to perform proxy forwarding
    

Add directives to ssl.conf

Edit /etc/httpd/conf.d/ssl.conf 

At the bottom of the VirtualHost element of the default (port 443) virtual server, insert the following (note the first line is redundant if this directive occurs earlier in the VirtualHost element):

# <== begin mod
#     by YourUserNameHere, DateOfModificationHere
#
# Grouper proxy forwarding
#
 
    ProxyPreserveHost on
  
    ProxyPass /grouper/ ajp://localhost:8709/grouper/

Once httpd is stopped and restarted, the ssl.conf changes above will be in effect.

Block port 8070

.... if it was opened in the firewall to prove correct installation prior to modifying ssl.conf, above

This prevents access via the usual http:// channel .... which is not desirable because it permits passwords to be passed insecurely

Grouper Configuration and Population

Overview

The following diagram illustrates:

• the required (orange) top-level bamboo stem in Grouper (this must actually be a top-level stem in the Grouper installation);
• the required stems beneath it (orange);
• required groups (orange); and,
• a set of illustrative example stems and groups
• a very sparse set of subjects (Bamboo Persons) populating a small sub-set of illustrated groups

1. bamboo: the top level node beneath which all Bamboo-relevant groups in this Grouper instance are located
2. bamboo:groups User-created stems and groups may be created as users desire; all such groups are created under the bamboo:groups stem
3. bamboo:admin Administrative stems and groups are segregated under the bamboo:admin stem:
   
   1. bamboo:admin:apps – groups under this stem represent application contractType, i.e., the types of relationship a known (registered) client may have to the Bamboo Trust Federation; expected contract types (and so required groups) are the groups indicated in the diagram, which themselves have as members groups that represent known (registered) applications (see bamboo:projects, below):
      
      1. bambooTrustFederation
      2. innovationLicensed
   2. bamboo:admin:membership – groups that represent types of institutional, organizational, or individual affiliation with Project Bamboo; note that no policies were implemented during the active period of the Bamboo Technology Project to demonstrate the utility of groups in this stem, nor are instructions given below re: populating this stem
      
      1. Bamboo memberships, such as partner, affiliate, guest, member – these groups might include principals that represent individuals, or institutions with which individuals prove affiliation at AuthN, etc. – to avoid heterogeneous memberships, institutional principals will be segregated from individual principals in different groups named in "sibling" relationships, e.g., "memberInstitutions" and "memberIndividuals"
      2. Institutional privileges, e.g., institutional subscriptions that permit Bamboo to grant access to IP-restricted content; an example of this type of membership group might be tcpPageImageSubscribers, a group that would be populated by entities that represent IdP identifiers. Conceptually (but not demonstrated in modeling of IdP identifiers or in example policies) a person who authenticates to an IdP where:
         
         • that IdP's authentication stands in for institutional affiliation, and where
         • that IdP's identifier is a member of tcpPageImageSubscribers,
         • would be permitted to access IP-restricted content governed by a policy that requires those conditions be true.
   3. bamboo:admin:roles – groups whose membership represents administratively granted roles, such as grouperAdminApps, qaTesters, bspServerAdmins, reAdmins; note that no policies were implemented during the active period of the Bamboo Technology Project to demonstrate the utility of groups in this stem, nor are instructions given below re: populating this stem
4. bamboo:projects – a stem within which are contained stems and groups that comprise registration of known client applications (or tools or services); see Grouper Install - Configure - Populate -- Fall 2013 corrections. Within this stem are:
   
   1. stems that represent projects, where a project might be an organization or research group that runs one or more client applications registered in the Bamboo Trust Federation
      
      1. groups within the stems that represent projects, where the groups represent a client application (or tool or service)
         
         1. for those client applications (or tools or services) which are Innovation Licensed, an administratively-defined set of (facade) Bamboo Person Identifiers (BPIDs) may be made members of the corresponding group to allow the Innovation Licensed app to be trusted to assert only those user identities when calling BSP-hosted services; the assumptions are that these BPIDs do not represent actual persons, and that Innovation Licensed apps are not actually authenticating users.

The following instructions assume that there is a Bamboo instance of Grouper installed, configured and running but with no Bamboo-specific content yet defined. The result of these instructions will be a fully populated base instance of Grouper for use by Bamboo projects.

Population of stems, groups, attributes

1. Log into the Bamboo Grouper UI (<base URL>/grouper/) as GROUPER_UI_SUPER_USER

2. Create the Bamboo folder immediately under "Root" in the Grouper UI

For the folder id field, use UUIDs generated by the site at http://www.famkruithof.net/uuid/uuidgen. Generate 10-15 at a time if you are going to be creating several folders or groups. Select "Version 4. Random" as the type. Then copy/paste successive UUIDs into the folder id and group id fields in the Grouper UI. These become the globally unique ids for the folders and groups.

Enter a description for the folder as indicated in the screen shot. Do this for each folder and group you create.

Since you clicked "Save and work in new folder" you will now be inside the root:bamboo folder and ready to create additional folders and groups as needed.

(3) Create the rest of the required Bamboo Grouper folder and group tree

It may be helpful to reference the Gliffy diagram in the Overview, above.

The bamboo:admin folder:

Within the bamboo:admin folder, create

An apps folder, with description "Bamboo application categories"

Within the apps folder, create a group

The group name should be bambooTrustFederation and the description should be "Applications with full membership in the Bamboo Trust Federation"; remember to provide a UUID in the group id field. Click "Save" when all the fields are entered.

Go back up one level to the apps folder and create a second group. The name should be innovationLicensed and the description should be "Applications in the Innovator License category."

Navigate back to the bamboo folder and create two more folders within it:

4. Optionally, create additional groups to represent standard membership categories and roles

Go back up to the bamboo:admin folder and create another folder. The name should be memberships and the description should be Bamboo Membership Categories

Inside the memberships folder, you may optionally create the groups listed below (or analogous groups that fit an applicable organizational model):

Back at the admin folder, create a third folder named roles with description Bamboo-wide Roles (or similar description).

Inside the roles folder, you may optionally create the groups listed below (or analogous groups that fit roles applicable in your organizational model):

5. Optionally, add folders and groups to represent known applications in the Bamboo Ecosystem

The process for adding applications is described on the page Grouper Install - Configure - Populate -- Fall 2013 corrections.

If, for example, you wish to add an Account Services application (cf. Grouper Install - Configure - Populate -- Fall 2013 corrections) to the suite of trusted client apps in the Bamboo Trust Federation, you might:

• Go to the projects folder and create a project folder within it named  accountLinkingService, description "Account Linking Service Project."
• Within that new folder create an associated application group, name "accountLinkingApp", description "Application Group for Account Linking Application."

See additional (and crucial!) details at Grouper Install - Configure - Populate -- Fall 2013 corrections.

Population of Subjects (persons)

Create Bamboo Persons (as needed)

The full process of creating Bamboo Persons involves creating the Bamboo Person (essentially, creating the associated BPID); creating or re-using a Contact for the person; and creating a Profile that specifies an associated Contact record (among other data). The APIs for the associated BSP-hosted services are:

• Bamboo Person service
• Bamboo Contact service
• Bamboo Person Profile service

The process of creating and managing identities is intended to be facilitated by a user-facing web application. This application was begun but not completed during the active period of phase one of the Bamboo Technology Project. It is described on the page Grouper Install - Configure - Populate -- Fall 2013 corrections. A link to the requirements document (outside this documentation tree) developed for the Account Services Module is linked from Grouper Install - Configure - Populate -- Fall 2013 corrections.

Create interim Subject Authority database (if not yet instantiated)

The following DDL both creates the necessary database and populates it with a set of special-case users necessary to the administration of the Bamboo Grouper instance and to BSP service access to the instance.

su postgres
$ psql
postgres=# drop database bbsubjectdb;
DROP DATABASE
postgres=# create database bbsubjectdb;
CREATE DATABASE
postgres=# GRANT ALL PRIVILEGES ON DATABASE bbsubjectdb TO grouper;
GRANT
postgres=# \q
$ psql
\c bbsubjectdb;
bbsubjectdb=# CREATE TABLE bbsubject (
bbsubjectdb(# BPId character varying (40) PRIMARY KEY,
bbsubjectdb(# name character varying (255) NOT NULL,
bbsubjectdb(# description character varying (255) );
grant all on bbsubject to grouper;
insert into bbsubject(BPId, name, description) values ('GROUPER_UI_SUPER_USER', 'GROUPER_UI_SUPER_USER', 'GROUPER_UI_SUPER_USER');
insert into bbsubject(BPId, name, description) values ('GROUPER_UI_ADMIN_USER1', 'GROUPER_UI_ADMIN_USER1', 'GROUPER_UI_ADMIN_USER1');
insert into bbsubject(BPId, name, description) values ('BSP_GROUP_SERVICE_USER', 'BSP_GROUP_SERVICE_USER', 'BSP_GROUP_SERVICE_USER');
insert into bbsubject(BPId, name, description) values ('BSP_READ_ONLY_SERVICE_USER', 'BSP_READ_ONLY_SERVICE_USER', 'BSP_READ_ONLY_SERVICE_USER');
\q
exit

Add Bamboo Persons to interim Subject Authority database

Assuming the above steps have been completed, and that UUIDs for the listed users have been properly obtained from the BSP-hosted Bamboo Person service, the following console log demonstrates how a record for the new user should appear post-creation. The instantiation of user test user 1 is given in the example as a new user with record creation syntax, again assuming that the UUID has been obtained from the Person service. Note that the console log uses an earlier version of PostgreSQL than is recommended in the installation instructions above (which itself is out of date as these instructions are published...).

[root]# su postgres
 
bash-4.1$ psql
psql (8.4.13)
Type "help" for help.
 
postgres=# \c bbsubjectdb;
psql (8.4.13)
You are now connected to database "bbsubjectdb".
bbsubjectdb=# select * from bbsubject;
                     bpid                      |            name            |                       description                 
       
-----------------------------------------------+----------------------------+---------------------------------------------------------
 BSP_GROUP_SERVICE_USER                        | BSP_GROUP_SERVICE_USER     | BSP_GROUP_SERVICE_USER
 GROUPER_UI_ADMIN_USER1                        | GROUPER_UI_ADMIN_USER1     | GROUPER_UI_ADMIN_USER1
 urn:uuid:04574969-e851-4fbf-8535-0b81b9b3f2f3 | earnest adams              | Ernie Adams from the Voronoi Project
 urn:uuid:c00f294d-651b-495b-9633-a900dd1a7418 | fred farkle                | Freddie Farkle from the Voronoi Project
 BSP_READ_ONLY_SERVICE_USER                    | BSP_READ_ONLY_SERVICE_USER | BSP_READ_ONLY_SERVICE_USER
 GROUPER_UI_SUPER_USER                         | GROUPER_UI_SUPER_USER      | GROUPER_UI_SUPER_USER
 urn:uuid:e1a6b81d-3c33-472b-95d6-34bce9a9fb80 | gwyneth peebles            | Gwyneth Peebles from the Roman Pleiades Project
 urn:uuid:41c8f60f-7287-4ac2-bec1-cd9fd3b85b69 | harriet smith              | Professor Harriet Smith from the Roman Pleiades Project
(8 rows)
 
 
bbsubjectdb=# insert
 into bbsubject(BPId, name, description) values 
('urn:uuid:985e5460-acf5-11e2-9e96-0800200c9a66', 'test user 1', 'Test 
User #1');
 
INSERT 0 1
 
bbsubjectdb=# select * from bbsubject;
                     bpid                      |            name            |                       description                 
       
-----------------------------------------------+----------------------------+---------------------------------------------------------
 BSP_GROUP_SERVICE_USER                        | BSP_GROUP_SERVICE_USER     | BSP_GROUP_SERVICE_USER
 GROUPER_UI_ADMIN_USER1                        | GROUPER_UI_ADMIN_USER1     | GROUPER_UI_ADMIN_USER1
 urn:uuid:04574969-e851-4fbf-8535-0b81b9b3f2f3 | earnest adams              | Ernie Adams from the Voronoi Project
 urn:uuid:c00f294d-651b-495b-9633-a900dd1a7418 | fred farkle                | Freddie Farkle from the Voronoi Project
 BSP_READ_ONLY_SERVICE_USER                    | BSP_READ_ONLY_SERVICE_USER | BSP_READ_ONLY_SERVICE_USER
 GROUPER_UI_SUPER_USER                         | GROUPER_UI_SUPER_USER      | GROUPER_UI_SUPER_USER
 urn:uuid:e1a6b81d-3c33-472b-95d6-34bce9a9fb80 | gwyneth peebles            | Gwyneth Peebles from the Roman Pleiades Project
 urn:uuid:41c8f60f-7287-4ac2-bec1-cd9fd3b85b69 | harriet smith              | Professor Harriet Smith from the Roman Pleiades Project
 urn:uuid:985e5460-acf5-11e2-9e96-0800200c9a66 | test user 1                | Test User #1
(9 rows)
 
bbsubjectdb=# \q
bash-4.1$ exit
exit
[root]#

Configuration of permissions on users and stems

Instantiation of users

The configuration of user permissions presumes prior creation of Grouper users. Cf. DDL in Population of Subjects (persons), above, re: adding the Grouper users described in this page's overview to the subject authority. Additionally, users must be declared and assigned passwords in a configuration file called tomcat-users.xml, described in some detail in the Importing an exported Grouper instance section, below.

The configuration file is located at ${GROUPER_INSTALL_DIR}/apache-tomcat-6.0.35/conf/tomcat-users.xml. Refer to the section Modify tomcat-users.xml to include necessary Grouper users and passwords, below, for detail about how to populate this file and to coordinate configuration with environment variables that must be set in Bamboo Services Platform runtime context (the environment variables configure BSP services with the user ids and passwords necessary to communication between the services and their backing Grouper instance).

Grant "GrouperSystem" level privileges to GROUPER_UI_SUPER_USER

The GROUPER_UI_SUPER_USER is a Grouper user meant to be utilized by a Bamboo administrator for login to the Grouper UI. Administrative login through the UI is the means by which clients of the Bamboo Ecosystem are registered, as described in Grouper Install - Configure - Populate -- Fall 2013 corrections. System level privileges must be granted to this user in order for it to possess the requisite privileges to perform the required operations. Grant GrouperSystem privileges as shown in the screen shot below:

Grant "ActAs" privilege to the BSP_GROUP_SERVICE_USER" via Grouper UI

The BSP_GROUP_SERVICE_USER is the login identity used by the BSP-hosted Group Service, which proxies Grouper for BSP clients. Taking advantage of the fact that the Group service has access to authenticated identity information about the user requesting read or write access to group data, the Group service acts as that user in calls to Grouper, and thus delegates management of authorization decisions for particular requests to the Grouper 'back end.' In order to enable this functionality, BSP_GROUP_SERVICE_USER must be granted ActAs permission, as illustrated in the screenshots below:

Grant all users create group and stem privileges on bamboo:groups

The bamboo:groups stem is a container for any arbitrary groups and stems that a Bamboo user wishes to create, where the stem/group creator has administrative privileges that s/he may grant to others (see Group Service API). To enable this functionality, all users are granted permission to create stems and/or groups, as illustrated in the following screenshots:

Importing an exported Grouper instance

su postgres
pg_dump grouperdb > myserver.grouperdb-todaysdate.sql
pg_dump bbsubjectdb > myserver.bbsubjectdb-todaysdate.sql

Overview

The following instructions should create a clone of an exported instance of Grouper complete with the Bamboo group hierarchy and interim subject database.

Files needed to clone

Export files

Examples:

• services-qa_grouperdb-20130323.sql
• services-qa_bbsubjectdb-20130323.sql

Grouper configuration files

• tomcat-users.xml (from directory ${GROUPER_INSTALL_DIR}/apache-tomcat-6.0.35/conf)
• sources.xml (from directory ${GROUPER_INSTALL_DIR}/opt/grouper-2.1.2/grouper.apiBinary-2.1.2/conf/)

Cloning / importing procedure

Shut down Tomcat container hosting Grouper

* Set $JAVA_HOME and stop the Tomcat container hosting the Grouper UI

* Shut down Grouper Tomcat
sh /opt/grouper-2.1.2/apache-tomcat-6.0.35/bin/shutdown.sh

Configure Grouper Properties

* Edit grouper.properties to enable wheel group (members of wheel group have privileges equivalent to GrouperSystem)
** in grouper.properties, change "groups.wheel.use = false" to "groups.wheel.use = true"

vim /opt/grouper-2.1.2/grouper.apiBinary-2.1.2/conf/grouper.properties
...
# A wheel group allows you to enable non-GrouperSystem subjects to act
# like a root user when interacting with the registry.
groups.wheel.use = true
...

Modify sources.xml to configure Grouper to use interim subject db

1. back up existing sources.xml at ${GROUPER_INSTALL_DIR}/opt/grouper-2.1.2/grouper.apiBinary-2.1.2/conf/
2. copy desired sources.xml, e.g.:

cp /var/tmp/grouper-exports/services-qa_20130323-modifiedForDev_sources.xml /opt/grouper-2.1.2/grouper.apiBinary-2.1.2/conf/sources.xml

<init-param>
  <param-name>dbDriver</param-name>
  <param-value>org.postgresql.Driver</param-value>
</init-param>
<init-param>
  <param-name>dbUrl</param-name>
  <param-value>jdbc:postgresql://localhost:5432/bbsubjectdb</param-value>
</init-param>
<init-param>
  <param-name>dbUser</param-name>
  <param-value>grouper</param-value>
</init-param>
<init-param>
  <param-name>dbPwd</param-name>
  <param-value>grouper_password</param-value>
</init-param>

Modify tomcat-users.xml to include necessary Grouper users and passwords

1. back up existing tomcat-users.xml at ${GROUPER_INSTALL_DIR}/apache-tomcat-6.0.35/conf/tomcat-users.xml
2. copy desired tomcat-users.xml, e.g.:

cp /var/tmp/grouper-exports/services-qa_20130323-modifiedForDev_tomcat-users.xml /opt/grouper-2.1.2/apache-tomcat-6.0.35/conf/tomcat-users.xml

<?xml version='1.0' encoding='utf-8'?>

<tomcat-users>
  <role rolename="grouper_user"/>
  <user username="GrouperSystem" password="BambooGrouperSystemPassword" roles="grouper_user"/>
  <user username="GROUPER_UI_ADMIN_USER1" password="tacm0t-" roles="grouper_user"/>
  <user username="BSP_GROUP_SERVICE_USER" password="tacm0t-" roles="grouper_user"/>
  <user username="BSP_READ_ONLY_SERVICE_USER" password="tacm0t-" roles="grouper_user"/>
  <user username="GROUPER_UI_SUPER_USER" password="tacm0t-" roles="grouper_user"/>
</tomcat-users>

Drop and re-create databases, import data: grouperdb and bbsubjectdb

Change to postgres directory (not necessary if the psql command is on the path), assure the database export files are accessible to the user postgres, and start a su session as the postgres user

sudo su postgres

(1) Terminate all sessions with the grouper database, drop it, recreate it and reload it

$ psql
Password:
psql (9.1.3)
Type "help" for help.

postgres=# select pg_terminate_backend(procpid) from pg_stat_activity where datname = 'grouperdb';
 pg_terminate_backend
----------------------
(0 rows)
postgres=# drop database grouperdb;
DROP DATABASE
postgres=#

(2) Re-create the grouper database and grant all privileges to the user "grouper"

postgres=# create database grouperdb;
CREATE DATABASE
postgres=# GRANT ALL PRIVILEGES ON DATABASE grouperdb TO grouper;
GRANT
postgres=# \q
$

(3) Import the new data from the export file

$ psql -d grouperdb -f /var/tmp/grouper-exports/services-qa_grouperdb-20130323.sql
Password:
[...]
ALTER TABLE
ALTER TABLE
ALTER TABLE
REVOKE
REVOKE
GRANT
GRANT
$
 

(4) Terminate sessions/connections, drop, then re-create the bamboo subject database and grant all privileges to the user "grouper"

$ psql
Password:
psql (9.1.3)
Type "help" for help.
postgres=# select pg_terminate_backend(procpid) from pg_stat_activity where datname = 'bbsubjectdb';
 pg_terminate_backend
----------------------
(0 rows)
postgres=# drop database bbsubjectdb;
DROP DATABASE
postgres=# create database bbsubjectdb;
CREATE DATABASE
postgres=# GRANT ALL PRIVILEGES ON DATABASE bbsubjectdb TO grouper;
GRANT
postgres=# \q
$

(5) Import the new data from the export file

$ psql -d bbsubjectdb -f /var/tmp/grouper-exports/services-qa_bbsubjectdb-20130323.sql
Password:
SET
[...]
REVOKE
REVOKE
GRANT
GRANT
$

(6) Perform another grant

$ psql
Password:
psql (9.1.3)
Type "help" for help.
postgres=# \c bbsubjectdb;
You are now connected to database "bbsubjectdb" as user "postgres".
bbsubjectdb=# grant all on bbsubject to grouper;
GRANT
bbsubjectdb=# \q
$

Sudo back to root

$ exit
logout
$ sudo su
#

Rebuild Grouper UI to incorporate Grouper configuration changes

(1) make Grouper ant executable: 

chmod +x /opt/grouper-2.1.2/apache-ant-1.8.2/bin/ant

(2) Rebuild UI

cd /opt/grouper-2.1.2/grouper.ui-2.1.2
export ANT_HOME=/opt/grouper-2.1.2/apache-ant-1.8.2
/opt/grouper-2.1.2/apache-ant-1.8.2/bin/ant war
----------
Buildfile: /opt/grouper-2.1.2/grouper.ui-2.1.2/build.xml
war:
... snip ...
BUILD SUCCESSFUL
Total time: 24 seconds
----------

Rebuild Grouper WS to incorporate Grouper configuration changes

cd /opt/grouper-2.1.2/grouper.ws-2.1.2/grouper-ws
/opt/grouper-2.1.2/apache-ant-1.8.2/bin/ant
----------
Buildfile: /opt/grouper-2.1.2/grouper.ws-2.1.2/grouper-ws/build.xml
checkGrouper:
... snip ...
BUILD SUCCESSFUL
Total time: 27 seconds
----------

Restart tomcat for Grouper UI

sh /opt/grouper-2.1.2/apache-tomcat-6.0.35/bin/startup.sh

Check to confirm successful imports

Wait a few seconds for Grouper to start, then browse to the Grouper UI.

https://bsp-dev.projectbamboo.org/grouper/

Log in, and you should see the data as imported from the exported PostgreSQL db files.

Hypothetical security approach to limit READ and VIEW access of user-created stems and groups

Approach

1. Do NOT grant READ and VIEW permissions on stems and groups to ALL users (a configuration setting).
2. Create a group that is "all Bamboo subjects other than BSP_READ_ONLY_SERVICE_USER"
3. Have Grouper rules that remove READ privileges on groups under bamboo:projects and bamboo:admin for members of the above group. (The effect is that only BSP_READ_ONLY_SERVICE_USER (and SysAdmin equivalent users like GROUPER_UI_SUPER_USER) will have READ privileges on those two stems.)

Implementing the approach

(a) Set READ and VIEW permission to FALSE in conf/grouper.properties. The properties in question are: groups.create.grant.all.read and groups.create.grant.all.view.

(b) Creating the group "all Bamboo subjects other than BSP_READ_ONLY_SERVICE_USER" would involve:

• defining a Grouper Loader job that went through the Grouper subject tables periodically and put each subject into a single group (call it "everybody") and then
• creating a composite group that was defined as "everybody" "minus" BSP_READ_ONLY_SERVICE_USER.

(c) To create Grouper rules that remove READ privileges groups under bamboo:projects and bamboo:admin for members of the group described in (a), above, cf. documentation on Grouper rules.