Page History

/groups/@me

{include:spaceKey=Grouper|pageTitle=Navigation}

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|https://wiki.terena.org/display/gn3pjra3/VOOT+-+Cross+Domain+Groupinformation+Exchange]).


The plugin developed for Grouper implements the version 0.9 of the VOOT protocol, you can find detailed scecification at the [Terena wiki page|https://wiki.terena.org/display/gn3pjra3/VOOT+specifications].
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|https://github.com/andreassolberg/voot/wiki/Protocol].


*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|https://spaces.at.internet2.edu/display/Grouper/Grouper+demo+site].

h3. 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.

h3. Retrieve Group Membership: 

{color:#000000}This call retrieves a list of groups the user is a member of:{color}

{code}
/groups/@me
{code}
or

{code}
/groups/{{userId}}
{code}
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) 

 

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

{code}
/people/@me/{{groupId}}
{code}
or

{code}

/people/{{userId}}/{{groupId}}
{code}
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) 

true]




{code}
{
  "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
}
{code}

[

]



{code}
{
  "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
}
{code}
[

]



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

]



{code}
{
  "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
}

}
{code}

h3. Installation

Here is the [README.txt|http://anonsvn.internet2.edu/viewvc/viewvc.py/i2mi/branches/GROUPER_2_0_BRANCH/grouper-misc/grouper-voot/README.txt?view=log]



{code}
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
{code}