AAI guide for VO managers

From EGIWiki
Revision as of 13:47, 7 September 2020 by Nmastor (talk | contribs)
Jump to: navigation, search


Introduction

This wiki page contains information about using the EGI AAI Check-in service from the VO manager's point of view. We provide a thorough guideline of the actions required in order to manage a Virtual Organization(VO). Furthermore, the reader will find information on how an eduPerson Entitlement gets created and what it stands for.

In the table below we provide a specimen of the eduPersonEntitlements a user should expect to be populated according to his roles or affiliation in the Virtual Organization.

Role Entitlement
VO Administrator
  • urn:mace:egi.eu:group:vo.example.egi.eu:admins:role=member#aai.egi.eu
  • urn:mace:egi.eu:group:vo.example.egi.eu:admins:role=owner#aai.egi.eu
VO affiliation member
urn:mace:egi.eu:group:vo.example.egi.eu:role=member#aai.egi.eu
VO role dummyRole
urn:mace:egi.eu:group:vo.example.egi.eu:role=dummyRole#aai.egi.eu

Glossary

Term Definition
CO (Collaborative Organizations) EGI User Community
COU (Collaborative Organization 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:
  • faculty
  • student
  • staff
  • alum
  • member
  • affiliate
  • employee
  • library-walk-in
eduPersonEntitlement Attribute value expressing group membership and role information

Abbreviations

Term Definition
EOF Enrollment Flow

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

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


Creating sub-COUs

sub-COUs can be created by Check-in platform administrators. To add or remove a sub-COU please contact Checkin Support indicating the following information:

  • sub-COU name
  • sub-COU parent COU name
  • sub-COU description
  • sub-COU scope (e.g. mailing list, other)
  • sub-COU administrators, i.e. one or more users responsible for managing sub-COU members
  • sub-COU owners, i.e. one or more users who can manage sub-COU members and appoint other users as sub-COU administrators

Viewing COU members

Visit EGI Check-in Registry
Registry endpoint.png
Click Login and authenticate using any of the login credentials already linked to your EGI account
Login.png
After logging in to the service, under Available Collaborations,
select EGI User Community from the list of collaborations.
Available colaborations.png
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)
People menu.png
Then you are able to see all COU’s members.
Cou members.png

Adding new members to a COU(EOF based)

Visit EGI Check-in Registry
Registry endpoint.png
Click Login and authenticate using any of the login credentials already linked to your EGI account
Login.png
After logging in to the service, under Available Collaborations,
select EGI User Community from the list of collaborations.
Available colaborations.png
Then expand the People drop down menu and click Enroll.
People menu.png
Copy the Begin link of the Enrollment flow of the VO you want the user to join and send it to the user
Join geoss eof.png
After the user concludes the Enrollment flow, s/he will find under Role Attributes the newly added VO.
Cou added.png

Adding existing members to a VO or Group

Visit EGI Check-in Registry
Registry endpoint.png
Click Login and authenticate using any of the login credentials already linked to your EGI account
Login.png
After logging in to the service, under Available Collaborations,
select EGI User Community from the list of collaborations.
Available colaborations.png
Then expand the People drop down menu and click My population if you are VO Manager or My <COU-name> Population
(for example, My vo.example.com Population) if you are only Group Manager.
People menu.png
Find the user you want to add to the new VO or Group and click Edit.
My Population.png
Click Add at Role Attributes section of the user
User Role Attributes Section.png
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
Add co person role form.png

Removing members

Visit EGI Check-in Registry
Registry endpoint.png
Click Login and authenticate using any of the login credentials already linked to your EGI account
Login.png
After logging in to the service, under Available Collaborations,
select EGI User Community from the list of collaborations.
Available colaborations.png
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)
People menu.png
Click Edit on the person that is going to be removed.
Cou members.png
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.
Cou removed.png

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
  • Navigate to Co Person Role view
    Co person role path.png
  • Choose Affiliation from drop down list
    Vo affiliation.png
Update User’s VO Role
  • Navigate to Co Person Role view
    Co person role path.png
  • Choose Role from drop down list, if available, or add custom text if no list is present.
    Role title.png

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

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

CO:COU:<COU_Name>:admins

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:

1. Visit EGI Check-in Registry
Registry endpoint.png
2. Click Login and authenticate using any of the login credentials already linked to your EGI account
Login.png
3. After logging in to the service, under Available Collaborations,
select EGI User Community from the list of collaborations.
Available colaborations.png
4. To view the available groups expand the Groups drop down list and click All Groups
Groups drop down.png
5. Expand the Filter section and find the COU admin group you are interested in.
For the case of the service-integration COU with type the string service-integration
in the text box with the placeholder Name. Then we click on Filter button
Expand filter.png
6. Locate Admins group click on Edit action
Groups actions.png

Assign COU member admin role

Following the steps defined above.

7. Follow Manage Group Memberships link
Manage group mem link.png
8. Filter out the CO Person you need to apply for the admin role.
Use Given, Family Name, Email, Identifier or a combination of the above
Co people filter.png

Remove COU admin role

Following the steps defined above.

7. Under Group Members tab, click on Delete action for the CO Person that needs to be removed from Admins group
Group members tab.png

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