AAI guide for VO managers

Overview

This wiki page contains information about using the EGI AAI Check-in service to manage Virtual Organisations (VOs).

VO management

This guide contains information about managing VOs. VOs in Check-in are represented as Collaborative Organisation Units (COUs). A COU is more than just a group. It is the concept of groups combined with membership management and advanced enrolment workflows. COUs can also be organised in a hierarchical structure.

It is assumed that COU administrators and members have already registered in https://aai.egi.eu/registry.

If you haven’t registered yet, please visit https://aai.egi.eu/signup

A step-by-step guide for the registration process is provided in the link below: https://wiki.egi.eu/wiki/AAI_usage_guide#Signing_Up_for_an_EGI_Account

VO membership API

Check-in provide a REST API that allows clients to manage membership information only for the VOs they are authoritative for.

Features:

• Members of the VO are identified via their EGI Check-in ePUID
• Membership can be limited to a specified period
• Different membership status values are supported, namely "Active, Expired, Deleted
• Check-in automatically changes the membership status from Active to Expired beyond the validity period

Authentication

The REST client is authenticated via username/password credentials transmitted over HTTPS using the Basic Authentication scheme. More sophisticated authentication mechanisms, such as OpenID Connect/OAuth 2.0 access tokens, may be supported in the future.

Methods

1. Adding a user to a VO requires specifying the user’s EGI Check-in ePUID, the name of the VO (e.g. vo.access.egi.eu in the case of LToS), the status (Active) and the valid from/through dates. All these parameters are mandatory. Here is an example using curl (see example add.json file below):

curl -vX POST https://aai.egi.eu/api/v1/VoMembers \
  --user "example-client":"veryverysecret" \
  --data @add.json \
  --header "Content-Type: application/json"

File: add.json

{
  "RequestType": "VoMembers",
  "Version": "1.0",
  "VoMembers": [
    {
      "Version": "1.0",
      "VoId": "vo.access.egi.eu",
      "Person": {
        "Type": "CO",
        "Id": "01234567890123456789@egi.eu"
      },
      "Status": "Active",
      "ValidFrom": "2017-05-21",
      "ValidThrough": "2017-06-21"
    }
  ]
}

2. Retrieving the VO membership information for a given EGI Check-in ePUID:

curl -vX GET https://aai.egi.eu/api/v1/VoMembers/01234567890123456789@egi.eu \
  --user "example-client":"veryverysecret"

Output:

[{"id":85,"epuid":"01234567890123456789@egi.eu","vo_id":"vo.access.egi.eu","valid_from":"2017-05-20T22:00:00.000Z","valid_through":"2017-06-21T22:00:00.000Z","status":"Active"}]

Beyond the valid_through date, the status will be automatically changed to Expired. So, when querying for VO membership information, it’s important to check that the status is actually set to Active for each of the identified VOs (see the vo_id attribute)

3. Updating existing VO membership record:

curl -vX PUT https://aai.egi.eu/api/v1/VoMembers \
  --user "example-client":"veryverysecret"  \
  --data @update.json \
  --header "Content-Type: application/json"

The request body is the same as the one used for adding new members but update requires using PUT instead of POST.

4. Removing VO member:

Same as the update but requires setting the membership status to Deleted