Grouper API

Owned by Julio Polo
Last updated: Oct 12, 2022 by mhodges
4 min read

Table of Contents

Request access to UH Grouper

Please complete the UH Groupings Request Form, even if you are only interested in Grouper.  Use the form's description box to provide this information:

  • Provide a description of your application, include the URL if applicable.
  • Provide a description of the groups you will need read access for.  You would normally choose from UH Group Store
  • If you will be creating your own groups, request the creation of a folder for your application:
    • Your own folder will need to fall under hawaii.edu:custom:<org> where <org> is one of the campus codes, which includes uhsystem for systemwide organizations
    • We ask you to create a folder for your department in addition to a folder for your application
  • Specify Grouper environment (test or production, you should start with the test environment)

You will get back a username and password to access Grouper

Typical Grouper operations

  • creating a folder or group
  • assigning permissions to folders or groups
  • searching for folders or groups
  • viewing group information (such as the group's ID Path which is used in requests, see below)

Code your application to talk to Grouper web services

Our Grouper web service currently uses basic HTTP authentication

  • Grouper username and password are included in the Authorization header of every HTTP request (your favorite HTTP or web service module should support this behavior, aka basic access authentication)

Use the group ID Path, not "Path"

  • Grouper can identify a group using two paths:
    • Group's ID Path:
      • e.g. hawaii.edu:custom:uhm:example-group
      • Note how the ID path uses codes ('uhm' instead of 'UH Manoa').
    • Group's path could be different from the group's ID Path in that we could use natural language, e.g. UH:Custom:UH Manoa:Example Group
      • In our experience, the added confusion created by this duality is not worth the friendlier names.
      • We recommend that everyone use the same value for a group's ID path and a group's path.
      • Exceptions to this recommendation may prove beneficial when the path contains words that are not in the ID path, thus allowing people to find your group.

Examples in this document interact with Grouper web services via REST and XML

Substitute Grouper version in examples' URLs with the actual version of the UH Grouper services:

  • Production URLS should begin with

    https://grouper.hawaii.edu/grouper-ws/servicesRest/xml/v2_2_002

  • Test URLS should begin with

    https://grouper-test.its.hawaii.edu/grouper-ws/servicesRest/xml/v2_2_002

The group's "ID Path" should be put into the request URL (and escaped):

  • For example, to get all members of hawaii.edu:custom:uhm:example-group above, your request URL would be

    https://grouper.hawaii.edu/grouper-ws/servicesRest/xml/v2_2_002/groups/hawaii.edu%3Acustom%3Auhm%3Aexample-group/members/

Quick Reference to some Grouper Constants

  • Subjects
    • Everyone: Subject name=EveryEntity, Subject ID = GrouperAll
  • Privilege Types
    • naming
    • access
  • Group privileges
    • admin (admin for group, can do everything)
    • optin (anybody can opt in to group)
    • optout (member can opt out of group)
    • read (can see a list of all members of group)
    • update (can add or delete members)
    • view (can see group exists)
  • Folder privileges
    • stem (create folder)
    • create (create group)
  • Grouper Attribute Framework
    • Attribute assignment types
      • group (group attribute)
      • imm_mem (Immediate membership attribute)
    • Attribute assignment operations
      • assign_attr
      • add_attr
      • remove_attr

Remember to click on download

For the links provided below, you'll need to click on the (download) link at the top

Checking if UH Number(s) are members of a Grouper group

Listing all members of a Grouper group

Adding members to a Grouper group

Deleting members from a Grouper group

New folders need to be explicitly granted create-group privilege

By default, a new folder only has the create-folder privilege granted to the person who created the folder. You need to explicity set the create-group permission for the folder creator:

Getting groups where user has admin privileges

Getting all groups that a person is a member of

POST calls do not populate the timestamp

Context:

Use these Grouper web service to add or delete members from the include or exclude groups.

https://spaces.internet2.edu/display/Grouper/Add+Member

https://spaces.internet2.edu/display/Grouper/Delete+Member

Required behavior:

REQUIRED: set the Grouper attribute to the current date and time, but truncate the seconds portion.  This requires an additional API call.

How to confirm that the timestamp is correctly updated: (you may need to request access to the UI)

Login to the UI.  For test grouper, that's grouper-test.its.hawaii.edu
Select Lite UI on the left
Manage attributes and permissions
View or assign attributes
Owner type = group
Attribute name (skip attribute definition), type last-modified and select the one that ends in mm (you have to select it even if you typed the whole thing):
uh-settings:attributes:for-groups:last-modified:yyyymmddThhmm
Owner group: type the name of your group AND SELECT IT (so it should be the one that ends in :include or :exclude depending on which one you touched)
Click on Filter button and you should see the timestamp for the group you entered above in the Assignment values field.