Grouper Voot Connector

Wiki Home	Grouper Release Announcements	Grouper Guides	Grouper Deployment Guide	Community Contributions	Internal Developer Resources

The Grouper VOOT Connector is a jar plugin for the Grouper WS which implements the VOOT protocol specification. VOOT is a protocol for exchanging group information externally to applications, defined within the GN3 JRA3 T2 (Identity Federations Task).

The plugin developed for Grouper implements the version 0.9 of the VOOT protocol, you can find detailed scecification at the Terena wiki page.
More recent versions of the protocol are still under definition phase, for an update on advancements you can refer to the VOOT specification github project.

Note: only the REST operations are implemented, not the OAuth 2.0. VOOT also described an authentication process based on OAuth.
This implementation inside Grouper delegates authentication to anything already implemented for Grouper WS and is pluggable in the same way that Grouper WS is. You can easily implement servlet container or web server basic auth without any effort. If someone has an OAuth 2.0 VOOT consumer and wants to work with the Grouper team to make OAuth 2.0 work with this plugin, let the Grouper team know.

This is currently running on the Grouper Demo Server.

Calls

The voot protocol defines two different sets of calls that can be made to a Grouper server: retrieve group membership and retrieve members of a group.

Retrieve Group Membership:

This call retrieves a list of groups the user is a member of:

/groups/@me

or

/groups/{{userId}}

where {{userId}} is replaced with an idenfier of the user at the provider.
The response can include the following keys:

(REQUIRED) id: The, to the provider, local unique identifier of the group;
(REQUIRED) voot_membership_role: The role the user has in this group;
(OPTIONAL) title: The short human readable name of the group;
(OPTIONAL) description: A description of the group.

The id field SHOULD be opaque to the client. The field voot_membership_role can be any of these values: admin, manager or member.

Retrieve Members of a Group:

This call retrieves a list of all members of a group the user is a member of:

/people/@me/{{groupId}}

or

/people/{{userId}}/{{groupId}}

Where userId is replaced with an identifier of the user at the provider and groupId is replaced with a group identifier which was obtained through for instance the call used to retrieve group membership for a particular user.
The response can include the following keys:

(REQUIRED) id: The, to the provider, local unique identifier of the user;
(OPTIONAL) displayName: The name by which the user prefers to be addressed;
(OPTIONAL) voot_membership_role: The role the user has in this group;
(OPTIONAL) emails: The email address(es) of the user;

The id field SHOULD be opaque to the client. The field voot_membership_role can be any of these values: admin, manager or member. The user MUST be a member, but not necessary have the role member of the group being queried. The emails field SHOULD contain a list of email addresses which provides the type to be any of work, home or other.
This call retrieves a list of groups the user is a member of:
/groups/@me
or
/groups/userId
Where {{
Unknown macro:

Unknown macro: {userId}

}} is replaced with an idenfier of the user at the provider. This
call MUST be supported. The response can include the following keys:
(REQUIRED) id: The, to the provider, local unique identifier of the group;
(REQUIRED) voot_membership_role: The role the user has in this group;
(OPTIONAL) title: The short human readable name of the group;
(OPTIONAL) description: A description of the group.
The id field SHOULD be opaque to the client. The field voot_membership_role
can be any of these values: admin, manager or member.
Retrieve Members of a Group

Mappings

The voot Group ID is the grouper group system name
The voot Group Name is the grouper group display name
The voot Group description is the grouper group description
The voot person email maps to the subject attribute name in the sources.xml file identified by emailAttributeName
The voot person id is the subject id
The voot person displayName is the subject name
The voot member admin role maps to the group admin privilege (note, if they are a grouper admin, they are also a member of the group)
The voot member manager role maps to the group update privilege (note, if they are a grouper update, they are also a member of the group)
The voot member member role maps to the group members list

Grouper extensions

If you pass in the request parameter indentResponse=true, then the resulting json will be indented

Examples

Ask the Grouper team for a user/pass to the grouper demo WS (currently basic auth via apache)

https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/voot/groups/@me?indentResponse=true

{
  "entry":[
    {
      "description":"",
      "id":"aStem:aGroup",
      "name":"aStem:A Group",
      "voot_membership_role":"member"
    },
    {
      "description":"",
      "id":"aStem:aGroup2",
      "name":"aStem:A Group 2",
      "voot_membership_role":"manager"
    },
    {
      "description":"",
      "id":"aStem:aGroup3",
      "name":"aStem:A Group 3",
      "voot_membership_role":"admin"
    },
    {
      "description":"",
      "id":"qsuob:all",
      "name":"QS University of Bristol:All Students and Staff",
      "voot_membership_role":"member"
    },
    {
      "description":"",
      "id":"qsuob:all_students",
      "name":"QS University of Bristol:All students",
      "voot_membership_role":"member"
    },
    {
      "description":"",
      "id":"qsuob:faculties:scif:students",
      "name":"QS University of Bristol:Academic faculties:Science:Students",
      "voot_membership_role":"member"
    }
  ]
  ,
  "itemsPerPage":6,
  "startIndex":0,
  "totalResults":6
}

https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/voot/groups?indentResponse=true

{
  "entry":[
    {
      "description":"Internal utility group for group mvmTestGroup which facilitates the group math for the include and exclude lists",
      "id":"users:penn2:mvm:mvmTestGroup_systemOfRecordAndIncludes",
      "name":"users:penn2:mvm:mvmTestGroup system of record and includes"
    },
    {
      "description":"",
      "id":"users:utah:earl.lewis:earlTestGroup",
      "name":"users:utah:earl.lewis:earlTestGroup"
    },
    {
      "description":"Group containing list of test2 after adding the includes and subtracting the excludes",
      "id":"users:penn:mchyzer:test2",
      "name":"users:penn:mchyzer:test2"
    },
    {
      "description":"Group containing list of addincludethingbwh after adding the includes and subtracting the excludes",
      "id":"users:penn:bwh:manilla:addincludethingbwh",
      "name":"users:penn:bwh:manilla:addincludethingbwh"
    },
    {
      "description":"Administrator",
      "id":"users:penn:teresh:admin",
      "name":"users:penn:teresh:Admin1"
    }
    #################ETC################
 ]
  ,
  "itemsPerPage":291,
  "startIndex":0,
  "totalResults":291
}

https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/voot/people/@me?indentResponse=true

{
  "entry":[
    {
      "displayName":"Barry Blair",
      "emails":[
        {
          "type":"email",
          "value":"babl@school.edu"
        }
      ]
      ,
      "id":"babl"
    }
  ]
  ,
  "itemsPerPage":1,
  "startIndex":0,
  "totalResults":1
}

https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/voot/people/@me/aStem:aGroup2?indentResponse=true

{
  "entry":[
    {
      "displayName":"Barry Masterson",
      "id":"bama",
      "voot_membership_role":"admin"
    },
    {
      "displayName":"Barry Blair",
      "emails":[
        {
          "type":"email",
          "value":"babl@school.edu"
        }
      ]
      ,
      "id":"babl",
      "voot_membership_role":"admin"
    },
    {
      "displayName":"Barry Windsor",
      "id":"bawi",
      "voot_membership_role":"admin"
    }
  ]
  ,
  "itemsPerPage":3,
  "startIndex":0,
  "totalResults":3
}

Installation

Here is the README.txt

To build the grouperVoot.jar
- Have grouper and grouper-ws project checked out and built
- Copy the build.example.properties to build.properties
- Configure the build.properties to point to grouper and grouper-ws
- Run the ant target build or distBinary

To run Grouper Voot
- Setup and run the grouper WS
- Copy the grouperVoot.jar to the WEB-INF/lib of grouper WS
- Make sure your sources.xml has an email attribute name in applicable subject sources:

     <!-- If using emails and need email addresses in sources, set which attribute has the email address in this source -->
     <init-param>
       <param-name>emailAttributeName</param-name>
       <param-value>email</param-value>
     </init-param>

- Setup the web.xml

  <filter-mapping>
    <filter-name>Grouper service filter</filter-name>
    <url-pattern>/voot/*</url-pattern>
  </filter-mapping>

  <servlet>
    <servlet-name>VootServlet</servlet-name>
    <display-name>Voot Servlet</display-name>
    <servlet-class>edu.internet2.middleware.grouperVoot.VootServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <servlet-mapping>
    <servlet-name>VootServlet</servlet-name>
    <url-pattern>/voot/*</url-pattern>
  </servlet-mapping>

- If you are using basic auth in the web.xml, make sure the voot servlet is protected:

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Voot services</web-resource-name>
      <url-pattern>/voot/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>grouper_user</role-name>
    </auth-constraint>
  </security-constraint>

- Voot documentation:

https://github.com/andreassolberg/voot/wiki/Protocol

- Turn on the grouper web services, and try the following URL's:

https://grouper.whatever.com/grouperWs/voot/groups/@me
https://grouper.whatever.com/grouperWs/voot/groups
https://grouper.whatever.com/grouperWs/voot/people/@me
https://grouper.whatever.com/grouperWs/voot/people/@me/aStem:aGroup2  [note: put in valid group name]

You can pass in a param to indent the response:

https://grouper.whatever.com/grouperWs/voot/groups/@me?indentResponse=true
https://grouper.whatever.com/grouperWs/voot/groups?indentResponse=true
https://grouper.whatever.com/grouperWs/voot/people/@me?indentResponse=true
https://grouper.whatever.com/grouperWs/voot/people/@me/aStem:aGroup2?indentResponse=true

This is running on the Grouper demo server e.g. here:

https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/voot/groups/@me?indentResponse=true
https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/voot/groups?indentResponse=true
https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/voot/people/@me?indentResponse=true
https://grouperdemo.internet2.edu/grouper-ws_v2_0_0/voot/people/@me/aStem:aGroup2?indentResponse=true

Page tree