Difference between revisions of "AAI guide for VO managers"
(Added structure for basic COU management) |
|||
Line 14: | Line 14: | ||
A step-by-step guide for the registration process is provided in the link below: | 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 | https://wiki.egi.eu/wiki/AAI_usage_guide#Signing_Up_for_an_EGI_Account | ||
== Glossary == | |||
== Creating COUs == | == Creating COUs == | ||
Line 22: | Line 24: | ||
== Removing members == | == Removing members == | ||
== Managing Affiliation and Role of VO Member == | |||
User’s '''Affiliation''' to a VO, as defined in [https://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-dir-eduperson-201203.html#eduPersonAffiliation 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. | |||
{| class="wikitable" | |||
| Update User’s VO affiliation | |||
| <ul> | |||
<li>Navigate to Co Person Role view | |||
[[File:Co person role path.png|none|frame]] | |||
<li>Choose Affiliation from drop down list | |||
[[File:Vo affiliation.png|none|frame]] | |||
</ul> | |||
|- | |||
| Update User’s VO Role | |||
| <ul> | |||
<li>Navigate to Co Person Role view | |||
[[File:Co person role path.png|none|frame]] | |||
<li>Choose Role from drop down list, if available, or add custom text if no list is present. | |||
[[File:Role title.png|frame|none]] | |||
</ul> | |||
|} | |||
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 | |||
Line 31: | Line 65: | ||
* Members of the VO are identified via their EGI Check-in ePUID | * Members of the VO are identified via their EGI Check-in ePUID | ||
* Membership can be limited to a specified period | * Membership can be limited to a specified period | ||
* Different membership status values are supported, namely <code> | * Different membership status values are supported, namely <code>Active</code>, <code>Expired</code>, <code>Deleted</code> | ||
* Check-in automatically changes the membership status from <code>Active</code> to <code>Expired</code> beyond the validity period | * Check-in automatically changes the membership status from <code>Active</code> to <code>Expired</code> beyond the validity period | ||
Revision as of 09:15, 31 March 2020
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
Creating COUs
Viewing COU members
Adding new members to a COU
Removing members
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