Documentation – Virtual Organisations

Users: Authorisation using VO information

Mon, 01 Jan 0001 00:00:00 +0000

Authorisation is the mechanism handling permissions and access control. While authentication deals with the identification of a user, authorisation determines and enforces what a user can do in the system.

This is depicted in the figure below, where a user access an application and authenticates through Check-in. If the authentication is successful, Check-in will share agreed user information with the application. As part of this information are the entitlements of the user, which encode the group and role membership of the user.

Services and applications typically use membership information to authorise user access to protected resources, so the entitlements play a relevant role in the authorisation task.

Entitlements

An entitlement is simply a string that encodes some user membership. Entitlements are formated as URNs, in this format:

<NAMESPACE>:group:<VO>[:<SUBGROUP>*][:role=<ROLE>]#<GROUP-AUTHORITY>

This format is described in the AARC-G069 specification:

Using this information, an application can determine that the user belongs to the the group “cloud” of the VO “vo.example.eu” and has the “operator” role assigned. With this, the application can make an authorisation decision whether or not to allow the user to access some resource or perform some action.

If a user has two roles in a group, then two different entitlements will be released for the user. For example, a user with roles “cloud_operator” and “data_operator” in the same group will have these entitlements:

urn:mace:egi.eu:group:project.vo.egi.eu:role=data_operator#aai.egi.eu

urn:mace:egi.eu:group:project.vo.egi.eu:role=cloud_operator#aai.egi.eu

When a user is not a member of a specific VO or group, or if the user’s membership has expired, the entitlement for this VO/group will not be released by Check-in.

Users: Group Management in Keycloak

Mon, 01 Jan 0001 00:00:00 +0000

Check-in allows you to organise your community based on two concepts:

Groups, representing a collection of users.
Roles, which are specific for each group and can be assigned to users individually.

Your community will be represented by a main group, often known as Virtual Organisation (VO). Inside your VO, you can have subgroups, and these can also have subgroups, creating a hierarchy.

Operationally, a VO can be considered a group as any other, with the particularity that it has a special behaviour (VOs cannot be deleted, and their membership must be renewed at least once every year), and that it is the root group, the highest group in its hierarchy. The hierarchy can be expressed as a “group path”. For example, the group path of the “External” group of the image is /community.eu/Testers/External.

Groups and roles allow you to manage authorisation. When a user belongs to a group or is assigned a role, he/she receives an entitlement, which is a string describing a permission the user has. For example, an entitlement looks like:

urn:mace:egi.eu:group:engineering.vo.egi.eu:role=member#aai.egi.eu

representing that the user is a “member” of the VO “engineering.vo.egi.eu”. See “Authorisation using VO information” for more details about entitlements.

Using these entitlements, an application can then make authorisation decisions based on the membership in a group. For example, to establish that only members of the group “cloud operators” can create virtual machines and manage infrastructure.

Structure of a group

Groups have two types of users:

Group Admins, who manage all aspects of the group, as well as any sub-groups in the hierarchy, including roles, membership, and settings. Groups can have one or more administrators.
Group members, who are the users that belong to the group.

Roles are defined per group and can be used to assign specific permissions within the group to users. Users inside a group can have one or more roles, but they must have at least one role within the group. By default, the role “member” exists for all groups.

The Group Admin of the VO is sometimes called “VO Manager”.

A Group Admin is also considered to be an administrator of all subgroups of the group (becoming an “indirect admin” for the subgroups), so these administration permissions propagate down the group hierarchy.

Users: Perun

Mon, 01 Jan 0001 00:00:00 +0000

How is this documentation organized

This documentation is specific for the EGI users and use cases. Each section briefly describes the concepts in Perun and available options. How-To guides for related common actions are available at the end of each section.

Overview

Perun is attribute management system, and within the EGI it provides an alternative solution for VO management. Perun provides more advanced features and supports complex use-cases compared to COManage and VOMS.

You should consider using Perun for VO management if you want or require the following features:

Customizable registration forms, flows, and notifications for both VOs and Groups
Advanced group management with group hierarchies and relations
VO/Group management roles delegation
Membership expiration/renewals rules
Membership sponsorships as exceptions to membership rules
Fine-grained access management for service owners
User/group synchronizations with external systems and services

VO management

Administrative GUI for VO managers is available at https://perun.egi.eu

It is assumed that VO managers and members have already registered their EGI Check-in account (A step-by-step guide is provided in this link).

Registering your VO

Standard EGI procedure for registering VO takes place. See related Check-In documentation about Registering your VO.

Steps that are specific to Perun are:

You will provide us with the necessary information through GGUS ticket (as described in the procedure).
You will register to your own VO using provided link, and we will set you as the VO manager.
You will register to your own VO using provided link, and we will set you as the VO manager.

Any further VO management and configuration is the responsibility of VO manager.

Managing members

All basic features regarding members management are available in the administrative GUI under the VO manager section. All features are described in the following sections in more detail.

Accepting new members

Users can register in your VO using the same registration link provided during the VO registration. It has the following format:

https://perun.egi.eu/egi/registrar/?vo=[voName] where [voName] is to be replaced with your actual VO name (as displayed on VO ID card in OperationsPortal).

Alternatively, you can configure an invitation notification template and send the registration link to the users directly from Perun.

Once the user submits the registration, it is up to you to review and approve or reject it. Perun can be configured to automatically approve valid registrations or reject them in case of user inactivity (for example when email is not verified by the user in timely manner).

There is a possibility to use custom registration modules that are programmable and can perform any specific and complex actions with the users and the VO. Please consult Perun user support using GGUS in case you need this feature.

Membership lifecycle, expiration rules and renewal

Almost identical features are available for each Group within the VO. See the same section under the Groups management for the differences.

By default, Perun expects that the membership lifecycle is managed by the VO manager directly - manually. This can be done by switching each members’ status between VALID, EXPIRED and DISABLED states or by removing the member from VO.

Members’ status affects which VO/group membership information is released to the service, hence affecting users’ ability to access the service or the state of users’ account in the service.

Member status	Meaning
`VALID`	User is active member of VO. VO/group membership information is provisioned to services (e.g. through Check-In proxy).
`EXPIRED`	User is inactive member of VO, but allowed to renew membership. VO/group membership information is not provisioned to services through Check-In proxy but can be provisioned to services directly connected to Perun.
`DISABLED`	User is inactive member of VO and can’t renew membership by himself. VO/group membership information is not provisioned outside of Perun.

Switching between the states can be automated based on membership expiration rules of VO or simply by setting membership expiration date manually to the member.

Notifications can be set to notify members about upcoming membership expiration. They can then ask for membership renewal using the same registration link. The Modified version of the form is displayed to them in such a case.

Membership expiration rules can be set either to a fixed date within the year (in such case member is expected to renew membership every year before that date) or be dynamically calculated based on the date of registration. In the second case renewal period can be shorter or longer than one year (e. g. +2y, +6m, meaning 2 years or 6 months respectively). In both cases, you also need to define the timespan, how long before the membership expiration are members allowed to ask for the renewal (e.g. 1m, meaning one month).

Managing groups

Groups are used to further categorize VO members within the VO and to assign them roles or access rights for the services. They can also be used to delegate members’ management to others as you can assign a group manager, which is then responsible for that particular group and its child groups.

All VOs have one system group named members, which automatically holds all VO members and can be used in groups relations.

Groups can be organized in a flat or hierarchical structure, or you can combine them as you need. Groups’ names must be unique on each level of hierarchy, and group full name consist of all groups names on the path from the root divided by colon :, e.g. projectX:students.

Top-level groups can be created only by the VO managers.

HOW-TO

Group memberships

Perun recognizes two kinds of group memberships, direct and indirect. If you use only flat group structure, all users are direct members of the groups. Once you start using hierarchical group structures or group relations, you will also get indirect members in some groups.

Both types of memberships are equal regarding the VO/group membership information released for the services (e.g. Check-In proxy).

Membership in the hierarchical group structures is inherited from the most bottom groups to the root, and the user can be both a direct and indirect member of the group at the same time.

Indirect members can’t be removed from the group and are displayed in the GUI using the italic font in the group members list. In order to remove them from the group you have to remove them from the sourcing subgroup first or remove relation between the groups.

HOW-TO

Accepting new group members

Group members can be added to the group directly by the VO/group manager chosen from the available VO members as described in the above How-To.

They can also register themselves using similar link like for VO registrations: https://perun.egi.eu/egi/registrar/?vo=[voName]&group= [groupName] where [voName] is to be replaced with your actual VO name (as displayed on VO ID card in OperationsPortal) and [groupName] is to be replaced with the groups full name (including hierarchy), e.g.: projectX:students.

All settings related to the group registration are basically the same as for the VO registrations, they are just located under the Group manager section in the GUI.

There is just one big difference regarding the registration workflow for the groups. The user must become a member of VO before the group registration can be accepted by the group manager (even automatically). The user is able to submit VO and group registration at once using a two steps form, but VO registration must be approved first.

Group membership lifecycle, expiration rules and renewal

Members’ lifecycle within the group is roughly the same as within the VO, but there are some differences.

Both VO and Group member status affect what vo/group membership information is provided to the services about the user.
Group membership statuses are only VALID and EXPIRED.
In hierarchical group structures, resulting in members’ status in a parent group is dependent on his/hers status in all child groups and VALID status takes preference.
Membership expiration in VO and group are independent of each other. Member can be expired just in some groups within the VO or be expired within the whole VO a still be valid within its groups. In such a case member is not considered as a member of VO by the services. Once membership is renewed, membership information is restored, including all groups.

Access management

While Perun generally uses the concept of Resources to represent the access rights and roles (as a service provider is giving them to the VO) and Groups are assigned to it (by the VO managers), it is not usually used like this within the EGI infrastructure.

Having Groups and Resources separated allows you to represent your community or organization structure without the conflict with the roles and access rights for each service. You can then more easily use one single group and give its members access to the various services with specific roles/settings. Any change to the group membership can then be reflected to all associated services, which is useful especially for the de-provisioning.

EGI Check-In proxy

For the primary and most basic use-case, when services are behind the EGI Check-In proxy, access rights are based solely on VO and group membership information.

Such information is then released by the EGI Check-In proxy as eduPersonEntitlement attribute conforming AARC-G002 specification.

Both VOs’ short name and groups’ full name are used to construct the entitlement value, so using correct naming for the group is required.

Association of specific VO/group membership value with the role or access rights within the service are the responsibility of the service provider.

Example

Let’s assume, that the user is a member of myvo.egi.eu VO and the top-level group vm_operator in it. Resulting eduPersonEntitlement will look like this: urn:mace:egi.eu:group:myvo.egi.eu:vm_operator:role=member#aai.egi.eu

Perun doesn’t support other roles within the groups than member.

VOMS

Note

Please note, that because of the nature of the VOMS, users must have personal certificate associated with their user entry in Perun in order to be provisioned to the VOMS at all.

Perun supports direct provisioning of the VOMS. In this use-case, users and VOs are primarily managed within the Perun. The user data, including group memberships and roles, is then provisioned to the VOMS, which is used solely as a backend for the services requiring it.

From the VO manager’s perspective, you are given a Resource by the service provider (VOMS operator). It represents your association with the VOMS in Perun. You can have multiple resources and they can represent either a different set of VOMS roles within the same VOMS or represent different VOMS servers.

You can assign any of your groups to it, and all users from all the assigned groups will be provisioned to the VOMS as members of your VO.

On the Service settings page of the Resource you can set VOMS roles, which will be given to all users associated with it through all the groups. Similarly, you can set VOMS roles on the Group-Resource level. Once you assign the group to the Resource, you can check Group settings page of the Resource, select the proper Group and set VOMS roles from there. The same group can have different roles for different VOMS servers like this. Also, you can associate group from Perun with the group in VOMS by settings Voms group name on the same settings page.

FAQ

I need all VO members to get “vm_operator” role in OpenStack

You must create a top-level group within the VO and name it vm_operator. All members of this group will get this role, and Check-In proxy will release this information as an entitlement for the OpenStack like this:

urn:mace:egi.eu:group:[VO_NAME]:vm_operator:role=member#aai.egi.eu

You can make sure all VO members are in this group by creating a relation between this group and the system group members (basically you include members as a subgroup through this relation).

Access with personal certificates

Due to historical reasons (wide adoption of VOMS), users might have their user entry in Perun already directly associated with their personal certificate. For such cases, direct authentication using the certificates is still available. Please consult Perun support through GGUS if you wish to merge your accounts and start using EGI Check-In as identity linking needs to be done on Perun side and not through EGI Check-In proxy.

Users: VOMS

Mon, 01 Jan 0001 00:00:00 +0000

Authentication

Some EGI services authentication is based on X.509 certificates. The certificates are issued by Certification Authorities (CAs) part of the EUGridPMA federation which is also part of IGTF (International Global Trust Federation).

The role of a Certification Authority (CA) is to guarantee that users are who they claim to be and are entitled to own their certificate. It is up to the users to discover which CA they should contact. In general, CAs are organised geographically and by research institutes. Each CA has its own procedure to release certificates.

EGI sites, endpoints and tools accept certificates part of the EUGridPMA distribution. If your community VO is enabled on that site, your certificate will be accepted by that site since all certificates are recognized at site level.

Usually, a certificate can be installed by command-line tools, but they can also be stored in the web browser to access EGI web tools and services.

Get a Certificate

The list of EGI recognised CAs provides a clickable map to find your nearby CA. Several of these offer the option to get an ’eScience Personal’ certificate online from the Terena Certificate Service CA. Check the countries where this is available.

If eScience Personal certificate is not available in your country, then request a certificate from a regular IGTF CA. The request is normally generated using either a web-based interface or console commands. Details of which type of request a particular CA accepts can be found on each CA’s site.

For a web-based certificate request, a form must usually be filled in with information such as the name of the user, home institute, etc. After submission, a pair of private and public keys are generated, together with a request for the certificate containing the public key and the user data. The request is then sent to the CA, while the private key stays in the browser, hence the same browser must be used to retrieve the certificate once it is issued.

Users must usually install the CA root certificate in their browser first. This is because the CA has to sign the user certificate using its private key, and the user’s browser must be able to validate the signature.

For some CAs, the certificate requests are generated using a command line interface. The details of the exact command and the requirements of each CA will vary and can be found on the CA’s site.

Once received the request, the CA will have to confirm your authenticity through your certificate. This usually involves a physical meeting or a phone call with a Registration Authority (RA). A RA is delegated by the CA to verify the legitimacy of a request, and approve it if it is valid. The RA is usually someone at your home institute, and will generally need some kind of ID to prove your identity.

Install a Certificate

After approval, the certificate is generated and delivered to you. This can be done via email, or by giving instructions to you to download it from a web page.

Browser installation

Install the certificate in your browser. If you don’t know how to upload your certificate in your browser have a look at the examples.

Host installation

To use EGI services with your certificate, you must first save your certificate to disk.

The received certificate will usually be in one of two formats:

Privacy Enhanced Mail Security Certificate (PEM) with extension .pem or
Personal Information Exchange File (PKCS12) with extensions .p12 or .pfx.

The latter is the most common for certificates exported from a browser (e.g. Internet Explorer, Mozilla and Firefox), but the PEM format is currently needed on EGI user interface. The certificates can be converted from one format to the other using the openssl command.

If the certificate is in PKCS12 format, then it can be converted to PEM using pkcs12:

First you will need to create the private key, use -nocerts. Open your terminal, enter the following command:
```
openssl pkcs12 -nocerts -in my_cert.p12 -out userkey.pem
```
where:

Filename Description

my_cert.p12 is the input PKCS12 format file;

userkey.pem is the output private key file;

usercert.pem is the output PEM certificate file.

When prompted to “Enter Import Password”, simply press enter since no password should have been given when exporting from keychain. When prompted to “Enter PEM pass phrase”, enter the pass phrase of your choice, e.g. 1234.
Now you can create the certificate, use -clcerts, (use -nokeys here will not output private key), and the command is:
```
openssl pkcs12 -clcerts -nokeys -in my_cert.p12 -out usercert.pem
```
When prompted to “Enter Import Password”, simply press enter since no password should have been given when exporting from keychain.

For further information on the options of the pkcs12 command, consult man pkcs12

Filename	Description
`my_cert.p12`	is the input PKCS12 format file;
`userkey.pem`	is the output private key file;
`usercert.pem`	is the output PEM certificate file.

It is strongly recommended that the names of all these files are kept as shown. Once in PEM format, the two files, userkey.pem and usercert.pem, should be copied to a User Interface (UI). For example, the ‘standard’ location for Mac would be .globus directory in your $HOME. I.e. $HOME/.globus/

Renewing the Certificate

CAs issue certificates with a limited duration (usually one year); this implies the need to renew them periodically. The renewal procedure usually requires that the certificate holder sends a request for renewal signed with the old certificate and/or that the request is confirmed by a phone call; the details depend on the policy of the CA. The certificate usually needs to be renewed before the old certificate expires; CAs may send an email to remind users that renewal is necessary, but users should try to be aware of the renewal date, and take appropriate action if they are away for extended periods of time.

Taking Care of Private Keys

A private key is the essence of your identity. Anyone who steals it can impersonate the owner and if it is lost, it is no longer possible to do anything. Certificates are issued personally to individuals, and must never be shared with other users. To user EGI services, users must agree to an Acceptable Use Policy, which among other things requires them to keep their private key secure.

On a UNIX UI, the certificate and private key are stored in two files. Typically they are in a directory called $HOME/.globus and are named usercert.pem and userkey.pem, and it is strongly recommended that they are not changed. The certificate is public and world-readable, but the key must only be readable by the owner. The key should be stored on a disk local to the user’s UI rather than, for example, an NFS-mounted disk. If a certificate has been exported from a browser, a PKCS12-format file (.p12 or .pfx), which contains the private key, will have been locally stored and this file must be either encrypted, hidden or have its access rights restricted to only the owner.

If a private key is stored under the Andrew File System (AFS), access is controlled by the AFS Access Control Lists (ACL) rather than the normal file permissions, so users must ensure that the key is not in a publicly-readable area.

Web browsers also store private keys internally, and these also need to be protected. The details vary depending on the browser, but password protection should be used if available; this may not be the default (it is not with Internet Explorer). The most secure mode is one in which every use of the private key needs the password to be entered, but this can cause problems as some sites ask for the certificate many times. Reaching a compromise between security and convenience is vital here, so that neither come too short.

It is important not to lose the private key, as this implies loss of all access to the services, and registration will have to be started again from scratch. Having several securely protected copies in different places is strongly advised, so the certificate can be used from a web browser and several UI machines.

A private key stored on a UI must be encrypted, meaning that a passphrase must be typed whenever it is used. A key must never be stored without a passphrase. The passphrase should follow similar rules to any computer password. Users should be aware of the usual risks, like people watching them type or transmitting the passphrase over an insecure link.

Authorisation

The sites authorise the access to their resources to a VO according to their own access policies, resource location, how many resources is the VO allowed to use. There are finer authorization policies, including groups, roles, in this way, the users can be structured in a VO. So, it is not a 0/1 authorization policy.

The community has full control of the access to the VO according to community authorization policies. The VO membership, groups and roles are managed by VO managers (Privileged VO members) independently by using the Virtual Organization Membership Service (VOMS).

VOMS

The Virtual Organization Membership Service (VOMS) is an attribute authority which serves as central repository for VO user authorization information, providing support for sorting users into group hierarchies, keeping track of their roles and other attributes in order to issue trusted attribute certificates and SAML assertions used in the Grid environment for authorization purposes. VOMS is composed of two main components:

the VOMS core service, which issues attribute certificates to authenticated clients
the VOMS Admin service, which is used by VO manager to administer VOs and manage user membership details.

How does it work? Usually, users submit tasks/jobs to the infrastructure that are attached with their own credential, and the credential is attached with a proxy certificate that is a short-term credential signed with the user certificate and is extended with the VO attributes. In general speaking, a user credential is just an ID, and a proxy contains the VO details, so a resource site by receiving the proxy can recognize that the user is part of such a VO with such a role from such a group. A user can be part of multiple VO, thus can generate multiple proxies.

Register to a VO

Visit Operation Portal to search for existing VOs

If there are any community VOs matching your requirements (with Registry System is VOMS), then click Action-> Details to look at the VO information. In the VO ID Card page, click the link for Enrollment URL, it will take you to the VO VOMS page. You should have already discussed with the EGI support team, they would help you to contact the VO managers and get approval for your access.
If there are no relevant VOs, you can send a request to register a new VO. (Note, for EGI services, you should request for VOMS configuration, once VO is configured, you will be notified about your VO VOMS link). More information can be found at Guideline for VO registration. Again, this is usually guided by the EGI support team. You should already have a meeting with them to discuss your requirements. They will help you to get resources from EGI providers, and sign SLA with you.
Request your VO membership at VO VOMS page. You will have to enter required information and then wait for approval.

Creating a proxy

VOMS configuration

Every VO needs two different pieces of information:

the vomses configuration files, where the details of the VO are stored (e.g. name, server, ports). These are stored by default at /etc/vomses and are normally named following this convention: <vo name>.<server name> (e.g. for fedcloud.egi.eu VO, you would have fedcloud.egi.eu.voms1.grid.cesnet.cz and fedcloud.egi.eu.voms2.grid.cesnet.cz.
the .lsc files that describe the trust chain of the VOMS server. These are stored at /etc/grid-security/vomsdir/<vo name> and there should be one file for each of the VOMS server of the VO.

You can check specific configuration for your VO at the Operations portal. Normally each VOMS server has a Configuration Info link where the exact information to include in the vomses and .lsc files is shown.

Proxy creation

Once you have the VO information configured (vomses and .lsc) and your certificate available in your $HOME/.globus directory you can create a VOMS proxy to be used with clients with:

voms-proxy-init --voms <name of the vo> --rfc

See for example, using fedcloud.egi.eu VO:

voms-proxy-init --voms fedcloud.egi.eu --rfc
Enter GRID pass phrase:
Your identity: /DC=org/DC=terena/DC=tcs/C=NL/O=EGI/OU=UCST/CN=Enol Fernandez
Creating temporary proxy ......................................................... Done
Contacting voms1.grid.cesnet.cz:15002 [/DC=cz/DC=cesnet-ca/O=CESNET/CN=voms1.grid.cesnet.cz] "fedcloud.egi.eu" Done
Creating proxy ................................................................... Done

Your proxy is valid until Mon Feb 4 23:37:21 2019