Navigation:
Documentation
Archive



Page Tree:

Child pages
  • Grouper Install - Configure - Populate

This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.

Skip to end of metadata
Go to start of metadata

These instructions are for installation, configuration, and population of Grouper 2.1.2 on a Linux box. The pre-installed database is presumed to be PostgreSQL 9.1.3. The installation instructions were followed/proven on a Linode VM running the Fedora 16 64-bit OS.

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 model employed to secure Grouper data, discussed in the overview section immediately following the Table of Contents on this page.

Note that Grouper-backed BSP functionality includes the Group Service (cf. Group Service Contract Description - v0.9-alpha) and data on known and trusted BSP clients (cf. Maintaining Application Catalog Data for Trusted Clients).

These instructions assume that a manual process is used to populate Grouper subjects in a custom subject database. This is an interim solution, pending development and deployment of a Subject Adapter that will use the BSP Person Service as a subject authority.

 

 

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. Group Service Contract Description - v0.9-alpha) and data on known and trusted BSP clients (cf. Maintaining Application Catalog Data for Trusted Clients).]

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:

User IDFunctionUsed ByNote
GrouperSystemSuper User - installation and system administrationInstaller / SysAdminIn general, this (default) user ID should not be used other than by a Grouper installer or system administrator of the application's host server.
GROUPER_UI_SUPER_USERSuper User - application (Grouper) expertApplication AdministratorThis user ID is intended for use by an administrator familiar with the Grouper application, e.g., to perform initial configuration and to manually repair unintended errors or corruption in the application data or configuration.
GROUPER_UI_ADMIN_USER1Super User - delegated administration of data pertaining to known and trusted client applications in the Bamboo ecosystem (cf. Maintaining Application Catalog Data for Trusted Clients). The data in question includes stems and groups under the top level stems bamboo:projects and bamboo:admin.Functional ("Bamboo") AdministratorThis user ID – or multiple IDs (incrementing the number at the end of the ID) if there are multiple individuals holding a functional administration role – is for use by those with a role in setting data that identifies known and trusted client applications; see link in cell at left.
BSP_GROUP_SERVICE_USERCredentials (this user id and corresponding password) utilized by the Group Service to read and write stem and group data in the top-level stem bamboo:groups. Calls using this user's credentials include an ActAs parameter that carries the subject ID of the subject who initiated a request to the Group Service that is being fulfilled by a call to the backing Grouper instance.Bamboo Group ServiceThis ID is used ONLY by the Bamboo Group Service, as indicated at left.
BSP_READ_ONLY_SERVICE_USERCredentials (this user id and corresponding password) utilized by BSP IAM infrastructure services in the course of verifying the status of a client application from which a request originated.Bamboo IAM utility servicesThis ID is used ONLY by IAM infrastructure services on the BSP, as indicated at left.

All stems and groups created in this Grouper instance, and the memberships of all such groups, are visible (readable) by any authenticated Grouper user. The following assumptions limit this visibility.

 

  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. Group Service Contract Description - v0.9-alpha.
  • Only BSP-hosted utility services (unavailable to end-users) have read access to stems and groups under bamboo:projects or bamboo:admin.


It is possible to configure a Grouper instance such that users are not universally granted READ and VIEW access to all groups and stems. Such a configuration was not attempted by the Bamboo Technology Project's implementation team. Because the Grouper instance utilized as a backing data store to BSP-hosted services was assumed to be a sole purpose instance, in which only the Grouper users listed above were instantiated, there was no use case or need to perform this more complex configuration. Some thoughts toward such a configuration are given below (cf. Hypothetical security approach to limit READ and VIEW access of user-created stems and groups), but deployers are cautioned to experiment carefully and test thoroughly to assure desired permissions are in place if employing a different configuration than that recommended above.

 


 

Installation

 

NOTE THAT:

  • these installation instructions describe Grouper 2.1 installation on a VM running the Fedora 16 64-bit OS; file locations, etc. may differ for other operating systems, please 'translate' carefully
  • pre-installed PostgreSQL is assumed; v9.1.3 was installed when these installation instructions were proven
  • $JAVA_HOME is assumed to point to a Java JDK, not just a JRE
  • regarding passwords:
    • note that passwords given in the instructions below are examples, and should be changed to appropriately secure passwords
    • the relevant environment variables used by Bamboo's Group and other services to set credentials for Grouper access must accurately reflect user names and passwords as set in Grouper; these environment variables are described on the page Developer Workbench Environment for BSP Service Developers; the Grouper users and passwords in question are set up post-installation, see below
  • user/installer typing is given in BOLD
  • assume RETURN at end of input lines unless otherwise noted
  • the notation [RETURN] is used where user response is to return to accept suggested/default input, or to follow input of single-letter input (in order to make that input more visible in the document)
  • Inline notes and console output to pay particular attention to are in  bolded maroon text
  • Square bracketed elipses indicated console output not reproduced in this document: [...]

 

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)

 

Make sure $JAVA_HOME points to a Java JDK, not just a JRE

 

 

$ 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
 

***** Open another terminal window, edit sources.xml to uncomment the PostgreSQL-specific SQL search command as described in console window instructions!! Proceed only when this is complete *****

 
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]#


You must open port 8070 in the Grouper host's firewall before remote access will work! However, this is not necessary (and, in fact, port 8070 should be CLOSED) once Apache Web Server (httpd) is configured to proxy forward over https. It is STRONGLY advised that httpd be configured and connection be made over SSL (https://...) PRIOR to logging in using a secure password. The maroon text below, including strikeout, reflects this advice.

 

Browse to Grouper UI at  http://<servername>:8070/grouper/  and login as GrouperSystem

[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 Configure Apache Web Server for Client Auth
  • 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/

 

Stop and restart the Apache web server

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

Omissions from this diagram:

  • to limit clutter in the diagram, the only groups shown as populated are groups that represent Innovation Licensed applications, tools, or services (see notes below re: bamboo:projects)
  • to limit clutter in the diagram, the groups xyz:1, xyz:2, and xyz:3 are shown as members of the group xyz; however the fact that they are also contained in a stem (presumably bamboo:groups) is not illustrated

 

Grouper_Hierarchy.gxml

  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 Maintaining Application Catalog Data for Trusted Clients. 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:

NameDescription
groupsBamboo user/researcher-managed Groups
projectsBamboo Projects - the related organizations or sub-organizations that manage known client applications (client apps)

 

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):

NameDescription
memberIndividualsIndividuals who are Members
memberInstitutionsInstitutional Members
affiliateIndividualsIndividuals who are Affiliates
affiliateInstitutionsInstitutions that are Affiliate Members
tcpPageImageSubscribersSubscribers to Text Creation Partnership Page Images

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):

NameDescription
bspServerAdminsBSP Server Admin Role
grouperAdminAppsApplications providing Grouper-related Services for Project Bamboo
qaTestersQA Tester Role
reAdminsResearch Environment Admin Role

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

The process for adding applications is described on the page Maintaining Application Catalog Data for Trusted Clients.

If, for example, you wish to add an Account Services application (cf. Account Services UI - Bamboo IAM Client - Drupal Module PoC) 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 Maintaining Application Catalog Data for Trusted Clients.


 

Population of Subjects (persons)

 

 

 

As of June 2013, software is not yet implemented to permit Grouper to use the Bamboo Person service as an authority from which to obtain valid Subject identifiers to represent persons who are members of groups.

Until this Subject Adapter is implemented (on the roadmap for Summer 2013), an interim authority must be made available within a Grouper instance. The creation of a separate database for this purpose is outlined below, and is also a part of the steps given for Importing an exported Grouper instance, the next major section of this documentation. Subjects added to any Bamboo group in the Grouper instance must first be added to this interim authority.

Note that the UUID values in the bpid field of this database must correspond to BPIDs that exist in the store backing the BSP-managed Bamboo Person service. This makes for an awkward, multi-step process, in which Bamboo Persons are first established via the Bamboo Person service, which sets a UUID to be used as the Bamboo Person Identifier (BPID). It is this BPID that must be added to the interim Subjects database. It's worth noting here that the process of establishing a Bamboo Person also includes establishing (or re-using) a Contact record via the Bamboo Contact service; and a profile for the person, via the Bamboo Person Profile service.

Once the Subject Adapter is implemented and running, Bamboo Person Identifiers (BPIDs) will be established via a client of the Bamboo Person service, as above; but these previously-established identifiers will be eligible for membership in groups without the manual step of adding them to an (interim) subjects database internal to Grouper.

NOTE TO DOCUMENTER: Documentation that replaces this section after the Subject Adapter is implemented should include reference to setting Grouper users and passwords in tomcat-users.xml.

 

 

 

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:

 

 

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 Account Services UI - Bamboo IAM Client - Drupal Module PoC. A link to the requirements document (outside this documentation tree) developed for the Account Services Module is linked from Identity and Access Management - Authentication and Authorization.

 

 

 

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

 

 

 

Passwords for the special-case users described above are set via their mandatory inclusion in tomcat-users.xml as detailed below. Please do not overlook the steps in that linked note that describe setting appropriate environment variables to configure BSP services to connect via the configured Grouper user names and passwords!

 

 

 

 

 

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 Maintaining Application Catalog Data for Trusted Clients. 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:



This step must be performed as the default Grouper super-user, GrouperSystem. Once this step is complete, further configuration through the UI can and should be performed as GROUPER_UI_SUPER_USER.

 

 

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

Note that these instructions assume the manual, interim solution re: using an internal subject database (rather than a Subject Adapter to the BSP Person Service) is in place.

Exporting the two (2) databases in play – the main Grouper database (grouperdb) and the internal subject database (bbsubjectdb) in play under this interim solution, as user postgres:

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

Some of the steps below may be done already. It's best to check.

Assumption is that the logged in user is sudo'd to root !!!

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

sources.xml must include the password for the postgres user grouper created during the install process described on this page, above, e.g. (cf. dbPwd node, at bottom of code block):

<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

Note that:

  1. the password for GrouperSystem must be set in tomcat-users.xml to the same value as is set at Grouper installation (or as subsequently changed for GrouperSystem); and
  2. Grouper user names used by the BSP Group Service, BSP_GROUP_SERVICE_USER and BSP_READ_ONLY_SERVICE_USER, and their passwords, must be set to values that correspond to environment variables set as instructed in the Setting Environment Variables section of the page Developer Workbench Environment for BSP Service Developers; and,
  3. Convenience logins to the Grouper UI, intended for use by administrators of the Bamboo Grouper instance, e.g., as described in Maintaining Application Catalog Data for Trusted Clients, must be set to values known by those administrators.

Example:

<?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

 


This step not necessary if NO CHANGES were made to sources.xml or tomcat.xml (i.e., if there was no need to perform the copy steps because the files were already properly set).

(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

This step not necessary if NO CHANGES were made to sources.xml or tomcat.xml (i.e., if there was no need to perform the copy steps because the files were already properly set).

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

 

The following are thoughts on a hypothetical approach to revamping Grouper security should a Bamboo ecosystem deployer desire different default permissions on user-created groups and stems (i.e., on groups and stems created under bamboo:groups).

The goals in this thought-exercise are to:

  1. Grant NO permissions on user-created groups and stems (in bamboo:groups) other than:
    1. those granted to the creator automatically, upon creation
    2. those granted by the creator (and possibly by fellow-administrators of the user-created groups and stems, should s/he designate any) explicitly, via calls to the Group Service API.
  2. Grant NO permissions on stems and groups under bamboo:projects and bamboo:admin except for:
    1. all permissions to users with a Sys Admin role (e.g., GrouperSystem, GROUPER_UI_SUPER_USER, GROUPER_UI_ADMIN_USER1)
    2. READ and VIEW permissions to the special-case user whose credentials are used by BSP IAM services: BSP_READ_ONLY_SERVICE_USER

This configuration was not attempted by the Bamboo Technology Project's implementation team. Because the Grouper instance utilized as a backing data store to BSP-hosted services was assumed to be a sole purpose instance, in which only the Grouper users listed above were instantiated, there was no use case or need to perform this more complex configuration.

Deployers are cautioned to familiarize themselves with Grouper documentation, experiment carefully, and test thoroughly to assure desired permissions are in place if employing a different configuration than that recommended above!

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.

  • No labels