Connectors for groups

This document is not final, but work in progress.

The Group connector is configured with a base URL, such as: https://api-group-datasource.no/groups

Authentication

Serverside TLS, HTTP Basic Authentication or Client certificate.

The Protocol

All requests are HTTP GET requests, and all responses MUST be JSON encoded.

Some endpoints may offer parameters passed through with a query string.

List of group protocol endpoints

Endpoint	Protocol description	Data returned
v1/{userid}/groups	The group memberships of a specific user	List of groups
v1/{userid}/groups/{groupid}	One users membership to one group	One membership object
v1/groups/{groupid}	Details about a group	One group object
v1/groups/{groupid}/members	Members of a group	A list of users
v1/groups	List all public groups	A list of groups

The userid is provided in the following format: feide:olanormann@uninett.no. The FeideID will normally be used to lookup groups, but the syntax allow for other types of userids. Dataporten will in example make use of national identity numbers nin:10107012345 in some use cases.

The groupids need to be globally unique, and include a prefix that allows the group engine to know which backend gruop connector to use to retrieve additional information from the group.

When a group connector is setup for a specific institution, it may agree upon a prefix with Dataporten, such as fc:g:ntnu.no:cerebrum or fc:g:uhad. Each group provided through these connectors must include the prefix in the identifier, in example fc:g:ntnu.no:cerebrum:idi:298387467. This examples are illustrative, just to show the idea, typically one should avoid using systemspecific names within the identifier, making it easier to replace an connector with a new conector remaining the group identifier intact.

The group memberships of a specific user

Returns a list of group objects. If groups have an start or end date, only return active groups.

Query string parameters:

• showAll=true return also inactive groups (in example with a passed end date)

{ 
    "meta": {}, 
    "items": [ 
        {group}, {group}, {group} 
    ] 
}

The users membership to a specifc group is embedded in the membership-property when groups are listed. Here is an example of a group object:

{ 
    "id": "fc:org:uninett.no:unit:avd-u20", 
    "type": "fc:orgunit", 
    "displayName": "Avdeling for System og Mellomvare", 
    "norEduOrgAcronym": "ASM", 
    "public": true, 
    "mail": "asm@uninett.no", 
    "membership": { 
        "basic": "admin", 
        "displayName": "Ansatt", 
        "affiliation": ["employee", "member"], 
        "primaryAffiliation": "employee" 
    } 
}

• Data model definition for group types in Dataporten

One users membership to one group

TBD

Details about a group

TBD

Members of a group

{ 
    "meta": {}, 
    "items": [ 
        {user}, {user}, {user} 
    ] 
}

Example of an user object:

{ 
    "userid_sec": ["feide:andreas@uninett.no"], 
    "name": "Andreas \\u00c5kre Solberg", 
    "email": "andreas.solberg@uninett.no" 
}

List all public groups

TBD

Data model

A user is member of a set of groups. For each group the user is member of, the membership is represented with the existence of an membership object. The membership object has no required properties, but a set of optional properties.

Properties of the group object are specific for the group and are the same for all members, while properties of the membership object are specific for each member.

All groups share some common properties, while there is a set of group type definitions that define extended attributes for different kind of groups.

• Data model definition for group types in Dataporten

For each configured group connector, a list of allowed group types is defined. New group types may be defined, and documented. It is important to avoid that for a given user the same semantic group is reflected in two duplicate groups (typically spanning multiple group connectors).