Op deze pagina vind je technische informatie over hoe je een extra 'Group' koppeling maakt tussen jouw Identity Provider-systeem (bijvoorbeeld Active Directory) en SURFconext. Je zult deze extra koppeling moeten implementeren naast de bestaande koppeling voor individuele gebruikers. Een reden om deze koppeling te maken is b.v. zodat je groepen die je in je lokale systeem al hebt en beheert, ook kunt gebruiken in combinatie met SURFconext Teams, in SURFconext Autorisatieregels en andere applicaties die overweg kunnen met informatie over groepen/groepslidmaatschap. Avans Hogeschool gebruikt deze optie bijvoorbeeld. 

Inleiding

Voor het uitwisselen van groepsinformatie tussen jouw Identity Provider-systeem en Service Providers maakt SURFconext gebruik van het VOOT-protocol, versie 2 (zie http://openvoot.org). VOOT staat voor Virtual Organization Orthogonal Technology. Dit protocol onderscheidt verschillende rollen:

• Group provider
• Client

Een group provider is een bron van groepsinformatie. Dit kan bijvoorbeeld jouw Identity Provider-systeem zijn, waarin staat wie in welke groep zit. Een client is een dienst (Service Provider) die gebruik maakt van deze groepsinformatie. Dit kan bijvoorbeeld een Wiki zijn, die bepaalde pagina's afschermt op basis van groepslidmaatschap (bijvoorbeeld alleen leden van de groep 'docenten' mogen een bepaalde pagina zien).

Beschrijving van het protocol

Als jouw organisatie in SURFconext groepen wil hergebruiken die je zelf definieert en beheert, dan word je gezien als een externe Group Provider. Je moet dan naast een koppeling voor individuele gebruikers ook een koppeling voor groepen maken met SURFconext. Dit doe je met behulp van het VOOT-protocol. VOOT staat voor Virtual Organization Orthogonal Technology.

Het protocol ondersteunt 2 manieren van authenticatie: Basic Authentication (RFC 2617) en OAuth 2.0 (RFC 6749). Wil je als externe Group Provider optreden in SURFconext, dan kun je alleen Basic Authentication gebruiken.

Je kunt het protocol zelf implementeren op jouw Identity Management-systeem of gebruik maken van een reeds bestaande implementatie. Bijvoorbeeld https://github.com/frkosurf/php-voot-provider.

Service Providers kunnen 2 verschillende typen verzoeken sturen naar jouw group provider via SURFconext:

* = Met UID wordt het attribuut urn:mace:dir:attribute-def:uid bedoeld. Deze wordt gebruikt om gebruikers binnen jouw Identity Provider uniek te herkennen. Zie de pagina over attributen voor meer informatie over dit attribuut.

Handleidingen

Om je op weg te helpen met het koppelen van jouw 'Group Provider' heeft SURFconext enkele handleidingen opgesteld:

Beveiliging interface

De VOOT-verzoeken die SURFconext stuurt zullen automatisch van de VOOT-omgeving komen. Om de gegevens te beschermen wordt altijd HTTPS gebruikt. De interface wordt afgeschermd met HTTP Basic Authentication met een door jullie aan SURFconext op te geven gebruikersnaam en (sterk) wachtwoord. Bij voorkeur stel je geen IP-adresrestricties op deze interface, omdat SURFconext op meerdere locaties gehost is en daarom vanaf verschillende ranges kan komen.

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

Institutions MUST 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 (VOOT) in draft and (OpenSocial) extensive. For this reason we provide an overview of the relevant parts of the protocol for the institutions 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. 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 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": "sysadmingroup",
            "title": "sysadmingroup",
            "description": "Super users",
            "voot_membership_role": "admin"
        },
        {
            "id": "demo_sprint_5",
            "title": "demo sprint 5",
            "description": "demo sprint 5",
            "voot_membership_role": "member"
        },
        {
            "id": "femke_1234",
            "title": "Femke 1234",
            "description": "Persoonlijke groep Femke",
            "voot_membership_role": "admin"
        }
    ]
}

The above JSON response example show all the fields that SHOULD be provided:

• id (This should be a local unique value)
• title
• description
• voot_membership_role

The following fields MUST be provided:

• id
• title
• voot_membership_role

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": "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": "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. The following fields SHOULD be provided:

• id (This should be a local unique value)
• name (familyName & givenName)
• displayName
• 1 email
• voot_membership_role

The following fields MUST be provided:

• id (This should be a local unique value)
• displayName
• voot_membership_role

For the authentication of the institution's endpoint either 3-legged OAuth version 1.0a or Authorization Code Grant OAuth version 2.0 MUST be supported. For the user experience the provider SHOULD connect the OAuth provider (responsible for creating and granting access tokens after a successful authentication) to SURFconext in order be establish SSO between the Service Provider, SURFconext and the External Group Endpoint.

Example VOOT/OpenSocial group clients

Microsoft Sharepoint

Microsoft Sharepoint as a group consumer

Example VOOT/OpenSocial group providers

PHP

https://github.com/fkooman/phOAuth - EXPERIMENTAL OAuth v2, only implicit grant profile
https://github.com/fkooman/phpvoot - EXPERIMENTAL Simple SQLite/LDAP backed VOOT group provider (OAuth v2 only, implicit grant only)

Microsoft Sharepoint

Microsoft Sharepoint as a SURFconext Group provider

Microsoft AD

Microsoft Active Directory as a Group Provider

Examples OAuth Service Provider:

Java

https://github.com/OpenConext/OpenConext-api

based on:

https://github.com/SpringSource/spring-security-oauth

C#:

https://wiki.surfnetlabs.nl/display/surfconextdev/OAuth+example+in+Csharp