Grouper Provisioning Plugin

The Grouper Provisioning Plugin provisions groups and memberships in groups to an Internet2 Grouper instance using the Grouper web services interface.

Operations

Provisioning of groups from Registry into Grouper is per CO with all groups for a CO provisioned under a single (configurable) stem or folder in Grouper. All groups in Registry, with the exception of the 'admin' and 'members' groups for COUs, are provisioned directly under the configured stem or folder for the CO. The 'admin' and 'members' groups for COUs are provisioned into a stem or folder hierarchy that mirrors the COU parent-child relationship (if any) in Registry.

Configuration

Prerequisites

Before configuring a Grouper Provisioner for a CO the Grouper deployment must be operational. Specifically you will need:

• Grouper web services (WS) deployed. The Grouper Provisioner invokes web service calls to provision to Grouper.
• A Grouper user that can authenticate to Grouper WS using basic authentication (a login and password). The authenticated Grouper user should have the necessary Grouper privileges to create folders, groups, and memberships in the stem or folder assigned for the CO. A common deployment pattern is to use the GrouperSystem user.
• Access to the Grouper configuration files in order to configure a COmanage Registry database view(s) as a Grouper subject source(s).
• Administrator access to the COmanage Registry database in order to create and then grant SQL SELECT privileges to a user that Grouper can use to query the Registry database view(s) supplying the Grouper subject source(s).

Configuration Steps

1. Ensure that the Registry database user (configured in database.php in the Config directory for your Registry deployment) has the CREATE VIEW privilege. For example with MySQL you might do

   GRANT CREATE VIEW ON registry.* TO 'comanage'@'localhost';

   if your Registry database is named 'registry' and the user is 'comanage'.

2. As the platform administrator or a CO administrator use the Collaborations menu to select the CO as the active working CO.
3. From the Configuration menu choose Provisioning Targets to open the Provisioning Targets view.
4. Click "Add Provisioning Target".
5. Complete the form for the new provisioning target:
   1. Enter a description for this provisioner, such as "Primary Grouper Deployment".
   2. Choose "Grouper Provisioner" as the plugin.
   3. Select "Automatic Mode" as the status.
6. Click "Add" to create the provisioner. A form to configure the Grouper Provisioner instance will be opened.
7. Complete the form to configure the Grouper Provisioner instance:
   1. Enter a URL with scheme and host for the Grouper WS instance, eg. https://some.server.edu
   2. Enter the context path on the server where the Grouper WS can be found, eg. /grouper-ws
   3. Enter the login for the user that will access the Grouper WS and invoke WS calls, eg. GrouperSystem
   4. Enter the password for the user that will access the Grouper WS and invoke WS calls
   5. Enter the full Grouper stem or folder under which the CO groups will be created. A typical deployment pattern is to use the name of the CO as the leaf stem, but it is not a requirement. If the stem does not exist the provisioner will attempt to create it.
   6. Choose the identifier to be used as the Grouper UI login identifier.
   7. Choose the email identifier to be used as the email attribute for the Grouper subject or user. A typical deployment pattern is to use the official email for the CO Person.
   8. The subject source view name is pre-populated with a default in the text box. We strongly recommend using the recommended default.  Please note the name of the view.
   9. Click "Save" to save the configuration.

8. The Grouper Provisioner automatically creates a (per-CO) SQL view that Grouper can use as a source of subjects or users. Before Grouper can use the view, however, you must create a user in your database and grant it SELECT privileges on the view. For example with MySQL you might enter 

   CREATE USER 'grouper'@'localhost' IDENTIFIED BY 'some_password';
   GRANT SELECT ON cm_co_grouper_subjects_1 TO 'grouper'@'localhost';

9. Grouper needs to be configured to use the view as a subject source. To do this you must edit the Grouper configuration file sources.xml and add a <source> element (and child elements) section for the database view for the CO. Note that a Grouper sources.xml file may include multiple <source> elements (some are for internal use by Grouper itself).

   Depending on the details of your Grouper deployment and how you manage it, you may need to edit the sources.xml file in three different places (the Grouper API, the WS tree, and the UI tree). You may, again depending on the details of your deployment, need to redeploy the Grouper WAR file(s). You will definitely need to restart the Grouper WS and UI after making changes to the sources.xml file(s).

   It is critical that the Grouper API (used for example by the Grouper loader), the UI, and the WS all use the same version of the sources.xml file, or you will experience unpredictable behavior with Grouper and the COmanage Registry Grouper Provisioner.

    

   1. A template of the text that needs to be added to the Grouper sources.xml file is attached and available here. The instructions that continue will refer to the attachment.
   2. Replace the UNIQUE_ID with a string that will be unique across all Grouper <source> elements in the sources.xml file. You might, for example, use the CO name. So if the CO is 'Test C0' then the UNIQUE_ID might be 'COmanage_Test_CO' (we recommend your UNIQUE_ID does not include any spaces).
   3. Replace the SOURCE_NAME with a string that represents this source. A typical deployment pattern is to use the name of the CO. This string will appear in the Grouper UI when clicking on a Grouper subject (user) to obtain details.
   4. Replace JDBC_DRIVER with the name of the JDBC driver that your Grouper installation will use to connect to the COmanage Registry database. For example, if you use MySQL for the COmanage Registry database then the driver would be 'com.mysql.jdbc.Driver'. If instead you use Postgres then the driver would be 'org.postgresql.Driver'.
   5. Replace JDBC_URL with a URL representation of the connection to your Registry database. The format of the URL will depend on which database you use for the Registry. For example, if you use MySQL and the name of your Registry database is 'registry' then the URL might be 'jdbc:mysql://localhost/registry?useUnicode=true&amp;characterEncoding=UTF-8'. If you use Postgres then the URL might be 'jdbc:postgresql://localhost/registry'. Please refer to the documentation for your database for details and to make sure that UTF-8 characters are supported.
   6. Replace DB_USER with the name of the database user that Grouper should use to connect to your Registry database.
   7. Replace DB_PASSWORD with the password for the database user.
   8. Replace COMANAGE_VIEW with the name of the view that Registry created when you configured the provisioner. The name of the view appears in the text box when you click 'Configure' for the provisioner if you need to retrieve it.
   9. Add the <source> element and its child elements to the Grouper sources.xml file(s). A typical strategy is to add it to the end of the file after any existing <source> elements, but before the closing </sources> element. Be sure to update ALL sources.xml files used by your Grouper deployment. Precisely how you do this will depend on how you manage your Grouper deployment, but a typical strategy is to find the sources.xml file under each of the grouper.apiBinary-2.2.1, grouper.ui-2.2.1, and grouper.ws-2.2.1 directories and update them (they should all be identical after your edits).
10. After editing the sources.xml file(s) restart the container (Tomcat) and if necessary the web server.

Testing

To test the COmanage subject source (view) for Grouper browse to the Grouper UI as a privileged user (often 'GrouperSystem'). In the UI search box (top right) enter the name of a person in the CO. Grouper should find the CO Person. Click on the user name to see the details that COmanage Registry makes available for Grouper.

Initial Reconciliation of Groups and Memberships

You can initiate the initial provisioning and reconciliation of groups and memberships from COmanage Registry to Grouper by choosing Configuration -> Provisioning Targets and then clicking 'Reprovision All' for the Grouper Provisioner instance you have configured.