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 |
Abbreviations
Term | Definition |
---|---|
EOF | Enrollment Flow |
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
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) |
|
Then you are able to see all COU’s members. |
Adding new members to a COU
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. |
|
Then expand the People drop down menu and click Enroll. | |
Choose and click the Enrollment flow of the VO you want to join, e.g. for VO vo.geoss.eu click Begin for the EOF Join vo.geoss.eu | |
Under Role Attributes find the newly added VO. |
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. In this example we removed the vo.geoss.eu that we previously added. |
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