How to work with VOMS

-- DRAFT -- NEEDS WORK -- DRAFT -- NEEDS CORRECTIONS -- DRAFT --

This is an overview of how:

• VOMS needs to work
• How to interact with a VOMS service
• VOMS aware resources need to work with VOMS credentials

Definitions

The list of definitions will introduce terms, patterns and also defines structures of data. The definitions will be used in the rules described below:

1. A 'User' can be a human, service or machine that is capable of presenting credentials (see definition #3) to establish its identity through a verifiable process.
2. A 'VOMS Attribute Provider' (VOMS-AP) is a service that gives out signed attributes for one Virtual Organizations indicating intra-VO group and/or role associations of a VO-member and/or service.
3. A 'VOMS server' can host one or more 'VOMS-APs'.
4. 'Credentials' are verifiable and trustworthy tokens that represent an particular identity of a User (see definition #0). The format of the 'credentials', e.g. SAML or ASN.1 conforming to RFC3281, is irrelevant for this generic term and MUST be specified if this makes argumentation ambiguous.
5. 'VOMS Attributes' are the signed attributes that VOMS-APs provide to a Users or a service with delegated credentials from a User. The User can present his own identity and the VOMS Attributes to other services for authentication and identity, group and/or role based authorization.
6. The 'VOMS Attributes' contain information of the VOMS-AP, VO (sub)group membership, VOMS Generic Attributes and possibly also contain Role affiliation. The Role affiliations are tied to a specific (sub)group in the VO. The User must explicitly request for Role affliations to be added. They also contain ties to the signer and ties to the User. The VOMS Attributes are signed by the VOMS-AP.
7. A 'Fully Qualified Attribute Name' (FQAN) is one string of characters that is one of the VOMS Attributes that hold a combination of group, subgroup and role. The role component is scoped to the (sub)group it is represented with. "/atlas/muon/Role=NULL" indicates a VO Atlas (the root or base group) and the group 'muon', without a specific Role defined. "/atlas/higgs/Role=Production" indicates a VO Atlas, and the group 'higgs'. The role 'Production' is specializing the group it is attached to.
8. The 'VOMS Generic Attributes' are name, value and qualifier triplets configured on the VOMS-AP and associated to a Credential belong to a User. The name, value and qualifier triplets are three string values. They can be configured by the VO Administrator, controlling the VOMS-AP, and configured by the user.
9. The Resource is any type of resource that can be used by a User to do any kind of work, i.e. a Resource can be a computing resource, batch queue, storage service or a portal.

Interaction rules between a User and a VOMS service

The following list describe the rules between a User and a VOMS service.

1. Any implementation of a VOMS-AP, regardless of the fact if it gives out signed ASN.1 formatted attributes (according to the OGF VOMS profile) or SAML-based attributes (not yet standardized), MUST provide the same semantic and pragmatic interaction as a result.
2. A VOMS-AP will decline to accept a command or query in the event that a User is unable to succesfully identity itself with Credentials. A protocol specific error SHOULD be returned to the User.
3. A VOMS-AP will return an VOMS specific error when the authenticated user is not a member of the VO that the VOMS-AP serves.
4. When a User authenticates to a VOMS-AP it can request VOMS Attributes or all possible VOMS Attributes known at the VOMS-AP for the presented identity of the User.
5. When a User requests VOMS Attributes from a VOMS-AP, the VOMS-AP will provide all VOMS Attributes that are VO specific groups and VOMS-GAs affiliated to the User sending the request.
6. The VOMS GAs are an unordered list of triplets, of which each element in the triplet is a string.
7. The returned list of VO group names is an ordered list. The returned list is ensured to be ordered as given. The signing process of the VOMS ACs MUST make the order of the list unchangeable without an error.
8. Users can request a list of all potential VOMS FQANs and VOMS GAs.
9. Users can request signed attributes. Without any specification a User implicitly requests all group and subgroup affiliations to be signed by the VOMS-AP and returned to the requester.
10. If a user specifies a role, which are implicitly group scoped, a list of FQANs will be return, of which the first element is the FQAN containing the group scoped role.
11. Users can request a second or more roles that they are affiliated to. The order in which the FQANs with roles are requested by the User will be the order in which these attributes will be listed in the VOMS Attributes list and in which order this structure is signed.
12. A User can request to embed VOMS Attributes for mulitple VOs in the same proxy. There is no upper limit in the amount of VO affiliation a User can have.
13. The User will request the VOMS Attributes per VO sequentially or pre-emptively specify which VOMS attributes will come first. On a VO bases this is ordered per complete VOMS Attributes of a VO. The ordering of the FQANs within the VOMS Attributes per VO will happen as a secondary stage to the VO ordering.
14. When a User requests VOMS Attributes for two or more VOs, the User is able to request a specific role. The request for a role will override the default VO request ordering and will ensure that the VO belonging to the role will be the first VOMS Attributes to be appearing before the other VOMS Attributes and as the first FQAN. As VOMS Attributes are used in blocks per VO, the VOMS Attributes of the first listed role will all preceed the VOMS Attributes of the second VO regardless of requesting an other role from the second VO.
15. When a User requests VOMS Attributes for two or more VOs, the User is able to request order FQANs of one or more VOs. The first listed FQAN in the reordered list of FQANs will override the default VO request ordering and override the reordering of the FQANs by request of an explicit role to be added. It will ensure that the VO belonging to the ordered requested FQANs will be the first VOMS Attributes to be appearing before the other and the first FQAN within that first set of VOMS Attributes.
16. Ordering and role requesting can both be invoked. The explicit ordering of VOMS FQANs wins from role request initiated reordering. A reordered requested FQAN can therefore reorder the returned VOMS Attributes per VO making the VO of the leading reordered FQAN come in front of other VOs.
17. The ordering and role requesting can be requested for any number of VOs and hence the following logic needs to be applied to each of the VOMS Attribute grouped per VO (N is less dominant to N-1):
    1. Ordering of explict FQANs
    2. Requesting an explict role
    3. VO Atrributes (without an explicit (set of) roles) in order of requested VO.

Interaction rules of how to renew the VOMS Attributes on behalf of the User

The following list describe the rules between a User and a VOMS service, when the VOMS service needs to renew the VOMS credentials.

1. The User MAY present credentials to a VOMS Attribute for renewal of the credentials to an VOMS-AP.
2. A VOMS-AP MUST verify that the User has presented sufficient credentials to identify the User.
3. A VOMS-AP MUST verify that the presented VOMS Attributes belong to the User.
4. A VOMS-AP MUST verify that the presented VOMS Attributes are valid and from a trusted mirror VOMS-AP or from itself.
5. Without an explicit FQAN reordering request, the VOMS-AP MUST return newly signed VOMS Attributes in the order in which they were presented to the VOMS-AP.
6. The returned set of VOMS Attributes MUST contain equal or less elements then the VOMS Attributes found in the presented User Credentials to authenticate the User to the VOMS-AP.
7. The User MAY requested a reordering of the VOMS FQANs. The VOMS-AP will need to follow this request and sign the attributes in the renewed order as requested.

Rules of how the VOMS Attributes need to be extracted at a resource

The following list describe the rules for a resource to extract VOMS Attributes from the presented credentials.

1. The User MUST present his VOMS Attributes with sufficient credentials to identify the User at a Resource.
2. The VOMS Attributes MUST be verified to be tied to the identity of the User.
3. When X.509 certificates, e.g. an RFC3820 proxy certificate or old-style GT2 proxy, are used to convey VOMS Attributes the chain must be traversed from the leaf certificate back to the root-CA. The first certificate that conveys VOMS Attributes is to be evaluated, all other certificates in the chain MUST be ignored. The same method MUST be used in other chain-like credentials.
4. When another, non-chained, User credential is used to convey VOMS Attributes, all of the VOMS Attributes are to be used.
5. The Resource needs to verify that the presented VOMS Attributes belong to the User's presented identity.
6. The advised method of trusting the VOMS Attributes is for the Resource to check the signatures of the VOMS Attributes and verify them against the VOMS-AP credentials. This source of the VOMS Attributes (a VOMS-AP) MUST be a trusted source.
7. The VOMS Attributes MUST grouped per VO and as such presented to the application or service in the order in which they were provided and signed by the involved VOMS-APs and the tool that requested the VOMS Attributes on behalf of the User.
8. The VOMS FQANs MUST be presented to the application/service in the order in which they were provided and signed by each of the VOMS-APs involved grouped per VO.
9. The VOMS Generic Attributes MUST be presented to the application/service as an unordered list grouped per VO.

Rules of how applications can work with VOMS Attributes

The following list describe the rules, options and opportunities for an application to interact/use the presented VOMS Credentials.

1. If a User requests a file, the Resource MAY request the User's Credentials which MAY include VOMS Attributes.
2. The User Credentials (with VOMS) can be used to determine read-privileges. The storage solution can require a (combination of) credentials to be passed from the User to the Resource and treated as an unordered list of credentials e.g.:
   • A Distinghuished Name from an X.509 certificate
   • A SAML based credential identifying the User.
   • A VOMS FQAN
   • A VOMS GA
   • A combination of VOMS FQANs
   • A combination of VOMS GAs
   • A combination of all of the above
3. The VOMS FQANs can be use ................ NEED TO WORK