DRAFT - WORK IN PROGRESS
SURFconext offers Service Providers an REST endpoint to query groups. The platform supports multiple sources for these Groups:
- SURFteams
- External Group Providers (e.g. groups from institutions)
The group memberships of a Person can be used to offer the logged-in user more context in a Service (e.g. in Google show the groups of the user as Google groups, show spaces based on the group memberships in the Confluence wiki or tabs in the Rave portal). Besides offering the logged-in user more context the groups can also be used as a source of authorization:
- Either the membership of a certain group is mandatory in order to log in to the Service Provider (this is enforced by SURFconext)
- Or the Service Provider uses the group memberships to limit the resources shown to the user (the SURFconext Confluence wiki is an example of this use case).
We strongly encourage institutions to follow the VOOT protocol when implementing their external group endpoint. The VOOT protocol is an extension of the OpenSocial protocol. The documentation of both the protocols is respectively in draft and extensive. For this reason we provide an overview of the relevant parts of the protocol on this page.
The external group provider endpoint provided by the institutions (in the remainder of this page referred to as 'endpoint') supports two methods:
- Get all groups (memberships) for a certain Person
- Get all members for a certain Group
The retrieval of all groups is a HTTP GET to /groups/@me or /groups/<user-id>. The /groups/@me will return all the groups for the person who has granted SURFconext access to his groups (using three-legged OAuth 1.0a or Authorization Code Grant OAuth 2.0). The /groups/<user-id> will retrieve all the groups for a specified user. It is up to the institution if it will grant the request (e.g. is the person who has initiated the exchange of an access token permitted to retrieve the groups for <user-id>?). The request must support the following query parameters:
- count
- startIndex
The count query parameter is the maximum number of groups to return. The startIndex query parameter indicated how many groups to skip (in order to support pagination). Example GET requests for group retrieval:
- https://<institution-domain>/<institution-subdomain>/groups/@me?count=100&startIndex=0;
- https://<institution-domain>/social/groups/user124323?count=25&startIndex=50;
- https://<institution-domain>/social/groups/@me
If the count and the startIndex are omitted then all the groups will be returned. The institution will respond with the groups in JSON format:
{
"startIndex": 0,
"totalResults": 3,
"itemsPerPage": 3,
"entry": [
{
"id": "urn:collab:group:test.surfteams.nl:etc:sysadmingroup",
"title": "sysadmingroup",
"description": "Super users",
"voot_membership_role": "admin"
},
{
"id": "urn:collab:group:test.surfteams.nl:nl:surfnet:diensten:demo_sprint_5",
"title": "demo sprint 5",
"description": "demo sprint 5",
"voot_membership_role": "member"
},
{
"id": "urn:collab:group:test.surfteams.nl:nl:surfnet:diensten:femke_1234",
"title": "Femke 1234",
"description": "Persoonlijke groep Femke",
"voot_membership_role": "admin"
}
]
}
The retrieval of memberships is a HTTP GET to /people/@me/<group-id>. The /people/@me/<group-id> will return all the members for the group <group-id> using the access token of the person who has granted SURFconext access to his groups. The request must support the same query parameters as in the group retrieval query:
- count
- startIndex
The count query parameter is the maximum number of members to return. The startIndex query parameter indicated how many members to skip (in order to support pagination). Example GET requests for member retrieval:
- https://<institution-domain>/<institution-subdomain>/people/@me/<group-id>?count=100&startIndex=0
- https://<institution-domain>/social/people/@me/<group-id>?count=25&startIndex=50
- https://<institution-domain>/social/people/@me/<group-id>
If the count and the startIndex are omitted then all the members will be returned. The institution will respond with the members in JSON format:
{
"startIndex": 0,
"totalResults": 2,
"itemsPerPage": 2,
"entry": [
{
"nickname": "Okke Harsta",
"emails": [
{
"value": "oharsta@zilverline.com",
"type": "email"
}
],
"voot_membership_role": "admin",
"id": "urn:collab:person:surfguest.nl:oharsta",
"name": {
"formatted": "Okke Harsta",
"familyName": "Harsta",
"givenName": "Okke"
},
"tags": [
"guest"
],
"accounts": [
{
"username": "oharsta",
"userId": "oharsta"
}
],
"organizations": [
{
"name": "surfguest.nl"
}
],
"displayName": "Okke Harsta"
},
{
"nickname": "Femke Morsch",
"emails": [
{
"value": "Femke.Morsch@surfnet.nl",
"type": "email"
}
],
"voot_membership_role": "admin",
"id": "urn:collab:person:surfnet.nl:morsch",
"name": {
"formatted": "Femke Morsch",
"familyName": "Morsch",
"givenName": "Femke"
},
"tags": [
"member"
],
"accounts": [
{
"username": "morsch",
"userId": "morsch"
}
],
"organizations": [
{
"name": "surfnet.nl"
}
],
"displayName": "Femke Morsch"
}
]
}
The above JSON response example contains many optional fields. We strongly recommends to support the following fields:
- id
- name (familyName & givenName)
- displayName
- 1 email
- voot_membership_role
The only non-optional fields are:
- id
- displayName
- voot_membership_role
For the authentication of the institution's endpoint we prescribe OAuth: either 3-legged OAuth version 1.0a or Authorization Code Grant OAuth version 2.0. For the user experience we strongly advise of connecting your OAuth provider (responsible for creating and granting access token tokens) to SURFconext in order be establish SSO between the Service Provider, SURFconext and the External Group Endpoint.
Examples OAuth implementations
There is no content with the specified labels