The COmanage Registry Grouper Provisioning Plugin is agnostic about the identifier used as the Grouper subject source. The only requirement from Registry is that it know the identifier and it is attached to the CO Person record either because Registry is creating it (eg. auto-generated identifiers) or because Registry has consumed it, perhaps during an enrollment or pipeline flow.

Grouper itself must be configured to search some service or repository to resolve the subject. Grouper calls the services or repositories subject sources. A Grouper deployment may have multiple subject sources. Common choices for Grouper subject sources are relational databases and LDAP directories.

If the identifier you want to use as the Grouper subject source is created by Registry, perhaps as an auto-generated identifier, you will need to make sure the identifier is provisioned as part of a person record that Grouper can be configured to use as a subject source. A common choice is to use the Registry LDAP Provisioning Plugin and provision the identifier as part of the CO Person record provisioned to LDAP and then configure Grouper to use LDAP as a subject source.

If instead the identifier you want to use as the Grouper subject source is simply consumed by Registry, for example during an enrollment flow (ePPN for example) or a pipeline flow, then you need to be sure that Grouper is configured to use some system where it can find that identifier as a subject source.

Configuration of subject sources for Grouper is discussed as this link.

 

A Grouper sources.xml file will 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.

 

 

The instructions below are only applicable if you are using the deprecated legacy mechanism for how Registry provisions the identifier for Grouper to use as a subject source. The database view mechanism is deprecated as of Registry 1.1.0.

Grouper needs to be configured to use the view created when the plugin was configured as a subject source so that it can find the CoPerson records for enrolled users to use as subjects or users. 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.

  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:3306/registry?autoReconnect=true&amp;CharSet=utf8&amp;characterEncoding=utf8

    Since the content of the file sources.xml is XML any '&' character in the JDBC URL query string must be escaped to '&amp;'

    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.2, grouper.ui-2.2.2, and grouper.ws-2.2.2 directories and update ALL of 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.
  11. Test the COmanage subject source by browsing 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.

  • No labels