Alert.png The wiki is deprecated and due to be decommissioned by the end of September 2022.
The content is being migrated to other supports, new updates will be ignored and lost.
If needed you can get in touch with EGI SDIS team using operations @ egi.eu.

Difference between revisions of "AAI guide for VO managers"

From EGIWiki
Jump to navigation Jump to search
(Replaced content with "{{TOC_right}} The documentation has moved to https://docs.egi.eu/users/check-in/vos/.")
Tag: Replaced
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{TOC_right}}
{{TOC_right}}


= Introduction  =
The documentation has moved to https://docs.egi.eu/users/check-in/vos/.
 
This wiki page contains information about using the [[AAI|EGI AAI Check-in service]] for managing your Virtual Organisation (VO).
 
= VO management =
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 for creating groups or subgroups within a VO.
 
It is assumed that VO managers and members have already registered their EGI Check-in account 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 user registration process is provided in the link below:
https://wiki.egi.eu/wiki/AAI_usage_guide#Signing_Up_for_an_EGI_Account
 
== VO registration ==
Any person who can authenticate to the [https://operations-portal.egi.eu/ Operations Portal] using their EGI Check-in account can register a new VO.
 
The person initiating the registration is called the '''VO manager'''. After the VO is set up and operational, the VO manager is the person who is primarily responsible for the operation of the VO and for providing sufficient information about VO activities for EGI and for VO members (to both people and sites).
 
A step-by-step guide for the VO registration process is provided in the link below:
https://wiki.egi.eu/wiki/PROC14_VO_Registration#VO_registration
 
== Viewing VO members ==
{| class="wikitable" style="width: 60%;"
| Visit EGI Check-in Registry
| [[image:Registry endpoint.png|thumb|none|300px]]
|-
| Click '''Login''' and authenticate using any of the login credentials already linked to your EGI account
| [[File:Login.png|thumb|none|300px]]
|-
| After logging in to the service, under '''Available Collaborations''',<br/>select '''EGI User Community''' from the list of collaborations.
| [[File:Available colaborations.png|thumb|none|500px]]
|-
| To view the existing members, expand the '''People''' drop down menu and<br/>click on '''My <VO-name> Population'''<br/>(for example, '''My vo.example.org Population''')
| [[File:People menu.png|thumb|none|300px]]
|-
| Then you are able to see all the VO members.
| [[File:Cou members.png|500px|thumb|none]]
|}
 
== Adding VO members ==
 
Users can request membership in your VO by following the VO enrollment URL. The enrollment URL has the following form:
 
<tt>https://aai.egi.eu/registry/co_petitions/start/coef:##</tt>
where <tt>##</tt> is a unique numeric identifier for the enrollment flow of your VO.
 
Once a user submits a VO membership petition, all VO managers are notified with an email containing a link to the petition. Any of the VO managers can then review the petition and either '''approve''' or '''deny''' the request.
 
The VO enrollment URL can be found through the EGI Check-in Registry:
 
{| class="wikitable" style="width: 60%;"
| Visit EGI Check-in Registry
| [[image:Registry endpoint.png|thumb|none|300px]]
|-
| Click '''Login''' and authenticate using any of the login credentials already linked to your VO manager EGI account
| [[File:Login.png|thumb|none|300px]]
|-
| After logging in to the service, under '''Available Collaborations''',<br/>select '''EGI User Community''' from the list of collaborations.
| [[File:Available colaborations.png|thumb|none|500px]]
|-
| Then expand the '''People''' drop down menu and click '''Enroll'''.
| [[File:COmanage Registry People Enrol.png|thumb|none|300px]]
|-
| Copy the '''Begin''' link of the Enrollment flow of the VO you want the user to join and send it to the user
|
[[File:Join example coef.png|500px|thumb|none]]
|-
| After the user concludes the Enrollment flow, s/he will find under '''Role Attributes''' the newly added VO.
| [[File:Joined example VO.png|500px|thumb|none]]
|}
 
== Adding existing members to a VO or Group ==
{| class="wikitable" style="width: 60%;"
| Visit EGI Check-in Registry
| [[image:Registry endpoint.png|thumb|none|300px]]
|-
| Click '''Login''' and authenticate using any of the login credentials already linked to your EGI account
| [[File:Login.png|thumb|none|300px]]
|-
| After logging in to the service, under '''Available Collaborations''',<br/>select '''EGI User Community''' from the list of collaborations.
| [[File:Available colaborations.png|thumb|none|500px]]
|-
| Then expand the '''People''' drop down menu and click '''My population''' if you are VO Manager or '''My <COU-name> Population'''<br/>(for example, '''My vo.example.org Population''') if you are only Group Manager.
|[[File:People.png|300px|thumb|none]]
|-
| Find the user you want to add to the new VO or Group and click '''Edit'''.
| [[File:My Population.png|500px|thumb]]
|-
| Click '''Add''' at Role Attributes section of the user
| [[File:User Role Attributes Section.png|500px|thumb]]
|-
| Fill the fields of the form and click '''Add''' . The user now is a member of the new VO or Group. For more information about Affiliation and Role fields you can see below at section '''Managing Affiliation and Role of VO Member'''
|[[File:Add co person role form2.png|500px|thumb]]
|}
== Removing members ==
{| class="wikitable" style="width: 60%;"
| Visit EGI Check-in Registry
| [[image:Registry endpoint.png|thumb|none|300px]]
|-
| Click '''Login''' and authenticate using any of the login credentials already linked to your EGI account
| [[File:Login.png|thumb|none|300px]]
|-
| After logging in to the service, under '''Available Collaborations''',<br/>select '''EGI User Community''' from the list of collaborations.
| [[File:Available colaborations.png|thumb|none|500px]]
|-
| To view the existing members, expand the '''People''' drop down menu and<br/>click on '''My <COU-name> Population'''<br/>(for example, '''My vo.example.com Population''')
| [[File:People menu.png|thumb|none|300px]]
|-
| Click '''Edit''' on  the person that is going to be removed.
| [[File:Cou members.png|500px|thumb|none]]
|-
| Under '''Role Attributes''' click  '''Delete'''  on the right of the COU  entry of interest (for example, vo.example.com).<br/>On success the selected row will be removed.<br/>In this example we removed the '''vo.geoss.eu''' that we previously added.
| [[File:Cou removed.png|500px|thumb|none]]
|}
 
== 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.<br/>
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" style="width: 60%;"
| 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.<br/>
According to the [https://aarc-community.org/guidelines/aarc-g002 AARC-G002 specification], a user that is a member of the VO vo.example.org, and has the role supervisor, obtains the following entitlements:
<pre>urn:mace:egi.eu:group:vo.example.org:role=member#aai.egi.eu</pre>
<pre>urn:mace:egi.eu:group:vo.example.org:role=supervisor#aai.egi.eu</pre>
 
== VO group management ==
VO groups can be created by Check-in platform administrators. Please contact [mailto:checkin-support@mailman.egi.eu Checkin Support] indicating the following information for every VO (sub)group that you need to add (or remove):
* '''VO name'''
* '''Group name'''
* '''Group description'''
* Optional, '''Group manager(s)''', i.e. the Check-in identifiers (in the form of <tt>"xxxxxxx@egi.eu"</tt>) of one or more users responsible for managing the VO group members. Group managers can also appoint other users as (sub)group managers. The manager(s) of the VO (or any parent group) are implicitly managers of the group. You can provide additional Check-in user identifiers to extend the list of group managers.
* Optional, '''Parent VO group name''' (in the case of a hierarchical group, e.g. <tt><VO> --> <PARENT_GROUP> --> <GROUP></tt>)
 
== Managing COU Admin members ==
 
COU Admin Groups are used to determine COU Administrators. Admin Groups are automatically created when a COU is created. The default name for COU admin groups is
 
<pre>CO:COU:<COU_Name>:admins</pre>
For example CO:COU:vo.example.org:admins
 
* A CO Person can be a member, an owner, both, or neither. Specifically:
** A COU admins group member can manage COU members:
** Approve or decline membership petitions
* Manage members’ roles
** A COU admins group owner has permission to add and remove members to and from the group, i.e. manage the list of CO Persons who can manage the COU members
 
A COU admins group owner can manage the admins group member as follows:
{| class="wikitable" style="width: 60%;"
| 1. Visit EGI Check-in Registry
| [[image:Registry endpoint.png|thumb|none|300px]]
|-
| 2. Click '''Login''' and authenticate using any of the login credentials already linked to your EGI account
| [[File:Login.png|thumb|none|300px]]
|-
| 3. After logging in to the service, under '''Available Collaborations''',<br/>select '''EGI User Community''' from the list of collaborations.
| [[File:Available colaborations.png|thumb|none|500px]]
|-
| 4. To view the available groups expand the '''Groups''' drop down list and click '''All Groups'''
| [[File:Groups drop down.png|300px|thumb|none]]
|-
| 5. Expand the '''Filter''' section and find the COU admin group you are interested in.<br/>For the case of the service-integration COU with type the string service-integration<br/>in the text box with the placeholder Name. Then we click on Filter button
| [[File:Expand filter.png|300px|thumb|none]]
|-
| 6. Locate '''Admins''' group click on '''Edit''' action
| [[File:Groups actions.png|500px|thumb|none]]
|}
 
=== Assign COU member admin role ===
Following the steps defined [[AAI_guide_for_VO_managers#Managing_COU_Admin_members|above]].
{| class="wikitable" style="width: 60%;"
| 7. Follow Manage Group Memberships link
| [[File:Manage group mem link.png|300px|thumb|none]]
|-
| 8. '''Filter''' out the CO Person you need to apply for the admin role.<br/>Use '''Given, Family Name, Email, Identifier''' or a combination of the above
| [[File:Co people filter.png|300px|thumb|none]]
|-
|}
 
=== Remove COU admin role ===
Following the steps defined [[AAI_guide_for_VO_managers#Managing_COU_Admin_members|above]].
{| class="wikitable" style="width: 60%;"
| 7. Under Group Members tab, click on Delete action for the CO Person that needs to be removed from Admins group
|
[[File:Group members tab.png|500px|thumb|none]]
|-
|}
 
= 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 <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
 
== 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. <code>vo.access.egi.eu</code> in the case of LToS), the status (<code>Active</code>) and the valid from/through dates. All these parameters are mandatory. Here is an example using curl (see example <code>add.json</code> file below):
 
<pre>
curl -vX POST https://aai.egi.eu/api/v1/VoMembers \
  --user "example-client":"veryverysecret" \
  --data @add.json \
  --header "Content-Type: application/json"
</pre>
 
File: <code>add.json</code>
<pre>
{
  "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"
    }
  ]
}
</pre>
 
2. Retrieving the VO membership information for a given EGI Check-in ePUID:
 
<pre>
curl -vX GET https://aai.egi.eu/api/v1/VoMembers/01234567890123456789@egi.eu \
  --user "example-client":"veryverysecret"
</pre>
 
Output:
<pre>
[{"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"}]
</pre>
 
Beyond the valid_through date, the status will be automatically changed to <code>Expired</code>. So, when querying for VO membership information, it’s important to check that the status is actually set to <code>Active</code> for each of the identified VOs (see the <code>vo_id</code> attribute)
 
3. Updating existing VO membership record:
 
<pre>
curl -vX PUT https://aai.egi.eu/api/v1/VoMembers \
  --user "example-client":"veryverysecret"  \
  --data @update.json \
  --header "Content-Type: application/json"
</pre>
 
The request body is the same as the one used for adding new members but update requires using <code>PUT</code> instead of <code>POST</code>.
 
4. Removing VO member:
 
Same as the update but requires setting the membership status to <code>Deleted</code>

Revision as of 00:59, 5 November 2020


The documentation has moved to https://docs.egi.eu/users/check-in/vos/.