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
Glossary
Term | Definition |
---|---|
CO (Collaborative Organizations) | EGI User Community |
COU (Collaboration Unit) | VO (Virtual Organization) |
Organizational Identity | User’s relationship with their "real" Identity Provider, e.g. University, Institute, etc |
CO Person | User belonging in EGI User Community COllaboration |
CO Person Role (EGI Community Title) |
User’s Role in a VO |
CO Person Affiliation (EGI Community Affiliation) |
User’s Affiliation with a VO as defined in RFC4512. Permissible values are:
|
eduPersonEntitlement | Attribute value expressing group membership and role information |
Creating COUs
COUs can be created by Check-in platform administrators. To add or remove a COU please contact Checkin Support indicating the following information:
- COU name
- COU description
- COU scope (e.g. mailing list, other)
- COU administrators, i.e. one or more users responsible for managing COU members
- COU owners, i.e. one or more users who can manage COU members and appoint other users as COU administrators
Viewing COU members
Adding new members to a COU
Removing members
Visit EGI Check-in Registry | |
Click Login and authenticate using any of the login credentials already linked to your EGI account | |
After logging in to the service, under Available Collaborations, select EGI User Community from the list of collaborations. |
|
To view the existing members, expand the People drop down menu and click on My <COU-name> Population (for example, My vo.example.com Population) |
|
Click Edit on the person that is going to be removed. | |
Under Role Attributes click Delete on the right of the COU entry of interest (for example, vo.example.com). On success the selected row will be removed. |
Managing Affiliation and Role of VO Member
User’s Affiliation to a VO, as defined in RFC4512, has eight permissible values. These are faculty, student, staff, alum, member, affiliate, employee, library-walk-in. EGI Check-in assigns to all user’s the affiliation Member by default, during the VO(COU) enrollment process. This value is immutable for the user but editable for the VO administrator. As a result, if there is a change of status the administrator can always step in and change it appropriately.
Additionally, the user’s Role in a VO is the EGI User Community Title column, in Co Person Role’s View. This column can be either a custom text value; or a value chosen from a drop down list. The drop down list administration is an EGI Check-in CO administrator task and can not be managed by any VO admin.
Update User’s VO affiliation |
|
Update User’s VO Role |
|
Subsequently, EGI Check-in uses the CO Person’s group membership and role information in order to construct the eduPersonEntitlement values, in short entitlements. These URN-formatted attributes can be used for representing group membership, as well as to indicate rights to resources.
According to the AARC-G002 specification, a user that is a member of the VO vo.example.org, and has the role supervisor, obtains the following entitlements:
urn:mace:egi.eu:group:vo.example.org:role=member#aai.egi.eu
urn:mace:egi.eu:group:vo.example.org:role=supervisor#aai.egi.eu
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
toExpired
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