...

Table of Contents

Overview

UH Groupings uses Grouper behind the scenes to implement the concept of a grouping.  This document specifies the Grouper operations that can be performed on a grouping.

Grouping Roles and Permissions

...

User Type	Description	Can use hawaii.edu/uhgroupings to perform these operations:
Grouping Superuser	Any person who has been designated as a Grouper administrator.	Can do everything in UH Grouper (and therefore UH Groupings)
Grouping Owner	Any person who is responsible for a grouping. The first owner requests for the creation of a grouping. That request must specify the basis and destination (if any) of the grouping.

 

	Can designate other people as Grouping Owners. Can add or delete people from the include and exclude groups. Can specify whether opt-in or opt-out is allowed for the grouping. Can enable or disable membership publication to a LISTSERV list for grouping Cannot change the basis using hawaii.edu/uhgroupings.  Must request these changes or it can be done through the API described on this page.
Grouping Member	Any person who is a member of a grouping, regardless of whether the membership comes from the basis or the include group.	Can opt in or opt out of a grouping, assuming the grouping owner allowed it
Application Account	A special username that is used by an application to interact with UH Grouper (and therefore, UH Groupings).  Grouper permissions are granted based on the needs of the application.	N/A, an application account can access whatever Grouper resources and perform whatever operations it has been granted

access to

permissions for.

 

Anatomy of a Grouping

All groupings must be created under hawaii.edu:custom:<org> or a subdirectory under that.  We'll describe the Grouper components that make up a grouping by using a manoa-math-club grouping example.  Remember that a colon delimits a folder, so we'll notate them in bold and ending with a colon:

Grouper web services

• All UH Grouping operations are performed using Grouper web services.  You will need to become familiar with it:
  
  • Grouper API

Application account

• If you will be using WS to read from or write to your grouping, make sure your Grouper application account has been granted the following privileges:
  • View and Read privileges on the grouping itself
  • Update privileges on the grouping's include and exclude subgroups.  This means your application account is also considered an owner for the grouping.

Checking if a person is a member of a grouping

• Determine the full path to the group that represents the grouping itself
  • e.g. hawaii.edu:custom:uhm:manoa-math-club
• Use this Grouper web service to check that the group has the UH Number of the person as a member:
  • https://spaces.internet2.edu/display/Grouper/Has+Member
  • e.g. to check that UH Number 11111111 is a member of hawaii.edu:custom:uhm:manoa-math-club
    
    • HTTP request (we'll be using the RESTful XML interface throughout our examples)
      
      • GET https://grouper.hawaii.edu/grouper-ws/servicesRest/xml/v2_1_005/groups/hawaii.edu%3Acustom%3Auhm%3Amanoa-math-club/members/11111111
      • Note how we had to URL-encode the colons in the group path.

    • HTTP response contains this XML (skipped some attributes to keep this example uncluttered)

      Code Block
      xml xml
      <WsHasMemberLiteResult> <wsGroup> <extension>manoa-math-club</extension> <typeOfGroup>group</typeOfGroup> <displayExtension>manoa-math-club</displayExtension> <description>UH Manoa Math Enthusiasts</description> <displayName>hawaii.edu:custom:uhm:manoa-math-club</displayName> <name>hawaii.edu:custom:uhm:manoa-math-club</name> <uuid>506f934c821459aee4</uuid> </wsGroup> <resultMetadata> <resultCode>IS_NOT_MEMBER</resultCode> <resultMessage> (some long message useful for Grouper debugging) </resultMessage>  <success>T</success> </resultMetadata> <responseMetadata> <resultWarnings></resultWarnings> <millis>216</millis> <serverVersion>2.1.5</serverVersion> </responseMetadata> <wsSubject> <resultCode>SUCCESS</resultCode> <success>T</success> <id>11111111</id> <name>John M Doe</name> <sourceId>UH core LDAP</sourceId> </wsSubject> </WsHasMemberLiteResult>

      
      

Adding or deleting people from the include or exclude groups

It is recommended that everyone use https://www.hawaii.edu/uhgroupings to manage every aspect of a grouping. 

...

• Special considerations before modifying an include or exclude group:
  • Who is performing the addition or deletion from the include and exclude groups?  If it as a grouping owner, you may proceed.
  • Is your application opting in or out on behalf of a grouping member?  If so, you should check whether the owner allowed that.
• Determine the full path to the grouping's include and exclude groups. Simply append :include or :exclude to the grouping path, e.g.
  
  • hawaii.edu:custom:uhm:manoa-math-club:include
  • hawaii.edu:custom:uhm:manoa-math-club:exclude
• 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: set this Grouper attribute to the current date and time, but truncate the seconds portion:
  
  • • The attribute name is uh-settings:attributes:for-groups:last-modified:yyyymmddThhmm
    • The attribute name in the web service call is referred to
  the current date and time, but truncate the seconds portion.
  
  Use this format:
  • • as wsAttributeDefNameName. See example below.
    • Set the attribute for the include or exclude group you are modifying, not the grouping path itself.
  • Use the YYYYMMDDTHHMM format for the attribute value, e.g.
    
    • 20140315T1915 (March 15, 2014 7:15:59pm59 PM, note how we truncated the secodsseconds, even if this should have been rounded to 7:16pm16 PM)
  • Please make sure your clock is synchronized with a time server.
  • Use this Grouper web service to assign the attribute:
    • https://spaces.internet2.edu/display/Grouper/Assign+Attributes

    • Example:

      No Format

      POST https://grouper.hawaii.edu/grouper-ws/servicesRest/json/v2_2_002/attributeAssignments { "WsRestAssignAttributesLiteRequest": { "wsAttributeDefNameName":"uh-settings:attributes:for-groups:last-modified:yyyymmddThhmm", "attributeAssignType":"group", "valueSystem":"20201231T1345", "wsOwnerGroupName":"hawaii.edu:custom:your:grouping:path:include-or-exclude", "attributeAssignValueOperation":"replace_values", "attributeAssignOperation":"assign_attr" } }

      
      

      
      

  • A future version of Grouper will support RabbitMQ messaging, and we should then do away with this timestamp requirement.

Reading attributes of group members

The following attributes are available when retrieving the members of a group:

• uid, uhuuid, cn, sn, givenName, displayName, uhOrgAffiliation, eduPersonAffiliation, eduPersonOrgDN, uhScopedHomeOrg

Multi-valued attributes will be returned as a single string with all values delimited by three vertical bars "|||".  THIS APPLIES ONLY TO THE Grouper API.  Do not expect this format to appear in other services such as UH Login or LDAP.

Example:

POST https://grouper.hawaii.edu/grouper-ws/servicesRest/xml/v2_2_002/groups
<WsRestGetMembersRequest>
 <wsGroupLookups>
  <WsGroupLookup>
   <groupName>path:to:your:grouping</groupName>
  </WsGroupLookup>
 </wsGroupLookups>
   <includeSubjectDetail>T</includeSubjectDetail>
 <subjectAttributeNames>
   <string>eduPersonAffiliation</string>
   <string>eduPersonOrgDN</string>
 </subjectAttributeNames>
</WsRestGetMembersRequest>

returns:

<WsGetMembersResults>

 <subjectAttributeNames>
  <string>eduPersonAffiliation</string>
  <string>eduPersonOrgDN</string>
  <string>uid</string>
  <string>cn</string>
  <string>sn</string>
  <string>givenName</string>
  <string>displayName</string>
  <string>eduPersonAffiliation</string>
  <string>eduPersonOrgDN</string>
 </subjectAttributeNames>

 ...

 <results>
  <WsGetMembersResult>
   ...
   <wsSubjects>
    <WsSubject>
     <resultCode>SUCCESS</resultCode>
     <success>T</success>
     <id>99999999</id>
     <name>First Last</name>
     <sourceId>UH core LDAP</sourceId>
     <attributeValues>
      <string>staff</string>
      <string>uhm</string>
      <string>username</string>
      <string>First Last</string>
      <string>Last</string>
      <string>First</string>
      <string>First Last</string>
      <string>staff|||student</string>
      <string>uhsystem|||uhm</string>
     </attributeValues>
    </WsSubject>
...