Skip to content
This repository has been archived by the owner on Jul 11, 2018. It is now read-only.

Home

Jump to bottom
Remold edited this page Jul 31, 2015 · 3 revisions

Syntax used

  • (a) Team: a group of people or groups, as created and manged by the Teams application (teams.demo.openconext.org)
  • (a) Group: an External Group of people as provided by an External Group Provider (EGP)

Enduser Documentation

For an example of documentation for end users of this type of collaboration platform, please have a look at SURFnet's (SURF)Teams documentation over at https://wiki.surfnet.nl/display/conextsupport/SURFconext+Teams

Administrator Documentation

Roles

  • member: can see who the other Team members are.
  • manager: same as member + can invite others, approve requests to join a Team and remove regular Team members.
  • admin: same as manager + can promote members to become 'manager' or 'admin', delete all Team members, edit the Team description and even delete the Team.

Any user of the OpenConext platform can use the Team application, but only OpenConext members can create a new Team. In general, OpenConext members are users who log in through the IdP of their institution (university). Users who login through a guest IdPs are OpenConext 'guests' and cannot create a Team. Guests can join a Team and become managers, but they cannot become admins.

To define which IdPs are institutional, and which are 'guest', please look at the documentation of Service Registry.

Invite Team members

Team members with the admin or manager role can invite others to become a member of the Team. New Team members are invited via email. To invite others:

  • Go to the detail view of the Team
  • Click on Invite members
  • Enter the email addresses in the "Email" field. Multiple addresses should be separated by a comma. It is also possible to upload a file that contains email addresses separated by comma by clicking the "Import CSV-file" link.
  • Choose the intended role for all invitees (available since version 2.4, https://jira.OpenConext.nl/jira/browse/BACKLOG-422)

For existing managers the only available option is to invite new members. If the new Team member is invited as admin, but the user logs in through a guest IdP, he will be made manager.

  • Customise the invitation message in the last field. It is advised to describe why you invite someone to this Team. Since version 2.5 the personal message is initially empty.
  • Submit the form

Join a Team

The "Public Teams" tab shows all Teams that are visible for all users. If you are not a member of a Team, you can request to join the Team.

  • All administrators of this Team receive an email that "John Doe ([email protected])" requests to join team "My Team" plus a personal message from the requester.
  • The administrator must go to the Team detail page (link is provided in the email) to approve or decline the request.
  • If a request is declined, the requester receives a mail notification.
  • New feature in version 2.5: if a request is approved, the new Team member receives a mail notification.

External Groups

For the Teams application all group providers are considered as External Group Provider except for groups coming from grouper.demo.openconext.org. Currently the Teams application only supports 3-legged OAuth 1.0a to communicate with External Group Providers. Maintaining the OAuth keys and secrets is currently done by end users via profile.demo.openconext.org. The Teams application checks for each user if OAuth keys and secrets are present. If they are present the Teams application assumes this user can get groups from this Group Provider. If the keys and secrets are no longer valid, the Team application will not be able to fetch groups and group membership information. The user must go back to profile.demo.openconext.org to update the OAuth keys and secrets.

Show External Groups in team.demo.openconext.org

Available since version 2.4, Jira issue: https://jira.OpenConext.nl/jira/browse/BACKLOG-369

In the home screen of the Teams application buttons appear for each External Group Provider. When a user clicks on an External Group Provider, all groups are shown of which this user has a membership. The user can then click further to see the other members of this external group.

The following REST calls are done by the Teams application towards the External Group Providers:

URI part Goal
groups/{userId} Get metadata of all groups this {userId} is member of
groups/{userId}/{groupId} Get the metadata of {groupId} where {userId} is member of
people/{userId}/{groupId} Get a list of group members for {groupId} with {userId} as "viewer"

Enable / disable functionality in the UI

If your organization does not want to show the External Groups to the end user, the functionality can be hidden in the user interface. The screens can still be retrieved when you know the URL behind it. This makes it possible to test the functionality or delay the go live without making a new version of the Teams application .

In coin-teams.properties 2 properties in coin-teams.properties are responsible to show/hide the new functionality in the user interface:

# If set to false, the link to external group providers will not be shown (only OpenConext Teams and Public Teams are visible)
displayExternalTeams=true

# If set to false, the link from the list of external groups to the detail view with their members is hidden
displayExternalTeamMembers=true

Link External Groups to a Team

Available since version 2.5, Jira issue:: https://jira.OpenConext.nl/jira/browse/BACKLOG-329

A Team is formed by individual members. This group membership is stored inside the Grouper database. The new functionality is to add External Groups to a Team in order to create a new (virtual) Team. The goal behind this is to make a Team with members of multiple institutions without adding each individual member in to a Team within OpenConext.

How to create a combined Team

  • Create a new OpenConext Team (or use an existing Team of which you are an admin).
  • If your account is configured to retrieve External Groups (see above) you get the button "Add groups".
  • The next screen will show all your External Groups that have not been linked to this Team. It is possible that you cannot link any External Group because either the Teams application received no groups from the External Group Provider or all your External Groups have already been linked to this Team.
  • Select the External Group(s) you want to link and submit the form.
  • The detail screen of the Team application will now show the External Group(s) that are linked to this Team, but not their members

Storage

The link between the Team and the External Groups is maintained in the the Teams application database. The Teams application stores besides the identifier also name and description of the External Group for 2 reasons:

  1. Performance: it avoids round trips to the External Group Provider when the details of the combined Team are displayed
  2. Access: when a Team contains groups from multiple Group Providers, not all members can normally access all the Group Providers

Currently we do not update the metadata in the the Teams application database. If this becomes an issue, we need to discuss how we can do this efficiently.

Enable / disable functionality in the UI

For each External Group Provider the the Teams application needs at least one member who gets the admin role for this Team in order to link External Groups from each institution.

The following REST calls are done by the Teams application towards the EGPs:

URI part Goal
groups/{userId} Get metadata of all groups this {userId} is member of

This functionality can be hidden in the user interface of the Teams application by changing the value of the following property in coin-teams.properties:

# Shows/hides the button to add an external group to a Team. If true, the button is visible
displayAddExternalGroupToTeam=true

Mapping of Teams roles to Grouper privileges

When adding users to a Team , the user is assigned a Team role (admin, manager or member). All Teams and memberships in Teams are stored in Grouper, including these roles. However, Grouper does has a different authorization model that is based on 7 privileges (member, admin, update, read, view, optin, optout). The following is the mapping between the Teams roles and the Grouper privileges:

Role Grouper privileges
admin member, optout, update, admin
manager member, optout, update, read
member member, optout, read

More information

  • [Configuring External Group Providers](Configuring External Group Providers)
  • [Mock External Group Provider](Mock External Group Provider)
  • [Service Provider Group ACLs](Service Provider Group ACLs)
Clone this wiki locally