Introduction
------------

UNICORE VO Service (UVOS) is a client-server system, developed to be used as an
additional tool for large distributed systems. Grid systems, especially UNICORE grid middleware,
are  the mainspring of the UVOS system. Although UVOS can be used with different systems, 
for the purpose of this document we will use the term 'grid system' to refer to  supported systems. 

The fundamental UVOS features are:

- storing identities of grid users and other identifiable components (for example servers),
- organising identities in hierarchical groups,
- assigning arbitrary attributes to users in various ways,
- registrations requests (or 'VO applications') support.
UVOS exposes those features as remotely accessible operations through the web service mechanism. 
This provides internal system access authorisation and authentication.

Typical usage patterns of the UVOS system include:

- grid node access authorization support, which enables granting access to members
of a particular group or owners of selected attributes
- mapping grid user identity onto another one (usually in different format),
- storing dynamic and static information about grid entities.
For more detailed information about possible ways UVOS can be deployed see 
xref:usage_scenarios[usage scenarios description].

The UVOS system is  build upon well established standards. For instance, all query operations 
used by clients are available through  the SAML 2 protocol. Moreover, the following optional 
SAML profiles are implemented to ensure interoperability:

- SAML Attribute Query Deployment Profile for X.509 Subjects,
- SAML Attribute Self-Query Deployment Profile for X.509 Subjects,
- OGSA Attribute Exchange Profile Version 1.2,
- XACML Attribute Profile.


UVOS Overview
-------------

UVOS is a component that acts as an information point and organises entities within a
hierarchical group structure. Top level groups of this structure are called virtual organisations.
Each _entity_ is assigned a list of group membership and a set of attributes. An attribute is
composed of a name and a set of values, which can be empty. In addition, a single entity can possess
multiple representations, for example in two different formats. These equivalent incarnations
of the same entity are called _identities_, and are usually invisible for an outside user.

Example
~~~~~~~
What follows is a comprehensive example of the UVOS database. It serves as an illustration of
various concepts which are presented in more detail later on. Please note that you can find
a script in the UVOS server distribution which creates the following example, 
so you can easily experiment with it.

Groups hierarchy:
--------------------------
[UVOS root]
|-Math-VO
|       |-Staff
|       |   |-Admins
|       |   |      |-u:UNICORE example user(DN)
|       |   |      |-u:Eve(email)
|       |   |-u:Amy(email)
|       |   |-u:Ben(email)
|       |-Scientists
|       |   |-u:Ben(email)
|       |   |-u:Andrew(DN)
|       |   |-u:Chris(email)
|       |-UUDB
|           |-SiteA
|           |-SiteB 
|-QSAR-VO
        |-u:Ben2(DN)
        |-u:Tom(DN)
        |-u:UNICORE example user(X509Cert)
--------------------------

Two top level groups, called VOs, are defined in this example. The first one (+Math-VO+) has a
complicated structure with subgroups, while the second (+QSAR-VO+) is very simple, with no subgroups. 
The users are presented with +u:+ prefix, along with their identity type in brackets. In this example
there are two equivalent identities (in other words: entity with two representations) of  
"UNICORE example user": of DN type and of X509Certificate type. 
"UNICORE example user" is the identity taken from the demo certificate which 
is distributed with UNICORE 6 quickstart package.


Entities
--------

Distinct members of the UVOS system are called entities. Every entity has a unique label and usually one
token that defines it. The token must be in one of the supported formats, which are: 

- X.509 certificate,
- DN - distinguished name,
- Email address.

A token along with it's type is called an identity. As explained an entity typically possesses
one identity, but it can also have more, even if they are of the same type. For instance, an entity with
the label "Jimmy Page" can have three identities: X.509 certificate issued by VeriSign, another X.509
certificate issued by ICM Warsaw University and an Email address jpage@example.com.

It is worth pointing out that all of the identities that compose an entity share the same characteristics 
(attributes, group membership, permissions, etc.). The UVOS works using entities, so that any of it's 
identities can be given as a representation.

Which type of identities shall be used?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are several things that influence the answer to the above question. We will give some simple 
rules which apply in typical UNICORE (or in general grid) situation.

First of all we can observe that DN and X.509 certificate are quite similar, namely certificate 
contains (in a certificate subject field) a user's DN. Also the fact is that grid sites  ask for 
DN type identity when authenticating or authorizing users.

So if it is enough administrator can use DN-type identities and forget about certificates. 
However it is often more comfortable for VO administrators to have a full entity certificate 
as it carries more data about the user. So in UVOS prior to 1.3 version, administrator usually 
created both identities - DN and X.509 - under a single entity. From the version 1.3 on 
it is not needed, as server was extended to use certificate also when asked for DN type identity 
(and obviously when there is no such a DN-type identity already defined). 
So when adding X.509 certificate identity is usually sufficient and it is not required to 
create DN-type identity.

The usage of email type identity is completely another story. It is used for two purposes:

- as a simple way to authenticate UVOS administrators
- to authenticate grid users to the web portals with a password.

So mail identity is required for regular gird users only as an additional identity 
(to the "base" DN or certificate type identity) when this user will access the grid through the WWW.


Attributes
----------

Attributes are composed of a name and a list of values. A name is a URN, and values are arbitrary strings. 
The value list can be empty.

The administrator can assign attributes to entities. There are three methods of doing this: :

- using *global attributes*: an entity can have an attribute assigned globally. Such an attribute
 is valid always and in every context,
- using *group-assigned attributes*: an attribute can be assigned to a group, in which case 
 all members of this group automatically hold this attribute (no matter if they were added later
 or prior to the creation of the group-assigned attribute). It is worth pointing out that this attribute
 is valid only in the scope of this group,
- using *group-scoped entity attributes*: those attributes are assigned to the entity, just like
  global attributes, but have an additional group restriction and are valid only in in the
  scope of the group.
  
The last two methods introduce a "group-scoped validity" of attributes, which requires a 
further explanation. From the technical point of view the requester can ask for the entity's
attribute in a specified group. Such a query will return all entity's global attributes and all
group-scoped attributes valid within this group. Considering the example situation shown above, 
the user Eve can have the "administrator" attribute in the scope of Math-VO (remember that
 a VO is just a normal group), but does not have it in VO QSAR-VO, where she is a regular user.
 
There is also another distinction between attributes, which is important only for query purposes:

- *effective attributes* are those that VO service consumer (e.g. Policy Decision Point) is
 interested in. SAML queries always return effective attributes. When querying without
  defining a group scope, all global attributes of the entity will be considered
  effective attributes. On the other hand, when querying an entity in the scope of
  a particular group  returned attributes contain both global and group-scoped attributes. 
  Note that attributes can be inherited – all attributes valid in the scope of the subgroup
  are also valid in the scope of the parent group.
  IMPORTANT NOTE: From the version 1.2 of UVOS server, group-scoped entity attributes override
  group attributes. Consider user U, who is a member of group G and  holds the attribute A with
  value VAL1 in the G group scope, but at the same time group G has an attribute A defined with
  value VAL2. The previous server versions returned both values (i.e. A with values VAL1, VAL2),
  while the current server release will return A with value VAL1 only.
- *exact attributes* have the the same functionality as effective attributes when considering global 
  and group-assigned attributes. The difference lies in group-scoped entity attributes. In such
  a case exact attributes assigned to ID1 in group G are simply those directly assigned to ID1
  in the scope of group G. They, for example, do not include attributes which are global or assigned
  to any of G subgroups (which are only considered effective attributes). Exact attributes
  are used in VO managing (administrator assigns exact attributes by definition), and 
  SHOULD NOT be used for authorization purposes.

Note: it is possible to assign group-scoped entity attribute even when the identity
isn't a member of the group. Consequently, this attribute will be visible as an exact
attribute only, and not as an effective attribute.


Authentication
--------------

Every request coming to the server is a subject of an authentication process. The authentication
result (whatever it is) is mapped to one of the identities available in service's database
- in other words there is no extra database with users of the VO service.
 
There are several issues here: to what type of identity requester should be mapped, and what
authentication mechanism should be used?

First of all you can enable different authentication data sources:

- *TLS* authenticated TLS session peer is mapped to an identity of X509 certificate type or DN type.
 The additional +uvos.server.authn.mapTLSCertToDNFirst+ property (boolean) controls which of those
 types is tried in the first place.
- *HTTP* an email type identity is created as obtained from HTTP BASIC authentication header and
 verified using a password, which is also set in the header.
 
Those options are tried in order, determined by configuration file parameter with name
+uvos.server.authn.order+. Administrator need not to enable both of them. Authentication
options which are used must be separated with a space character. The first identity in
order that is successfully verified (and present in database) is used. If there is
identity found which is invalid or not present in database, the authentication process can 
either continue checking the next possibility or fail. This is controlled by configuration
option +uvos.server.authn.failOnError+. Note that it effectively makes sense only when
you have both options enabled.

Note that this form of authentication was introduced in the version 1.3.2, earlier versions
used a more complicated one.


UVOS access authorization
------------------------

UVOS access is restricted by it's own authorization stack. No external components/services are 
used to perform authorization. The first part of this section describes in detail the whole
authorization process. The system is flexible however quite complicated too. Therefore
2nd part shows simple set of rules (also employed in default configuration) that allow 
for easy configuration of secure UVOS access. It should be enough for the most of
applications. Readers are encouraged to at least briefly scan the initial paragraphs of
the next section before proceeding to the second one.

Authorization overview
~~~~~~~~~~~~~~~~~~~~~~

While accessing an operation requires the accessing entity to possess zero or more Permissions, 
in most cases at least one is needed. The following permissions are defined:

- *read (r)* - this permission is needed to perform various operations that read current VO contents.
- *fullRead (f)* - this permission is needed to read special VO contents like historical data or
 hidden attributes.
- *identityCtl (i)* - this permission is needed by operations that are used to manage
 identities (add/remove).
- *write (w)* - this permission allows for changing VO contents and UVOS authorization configuration.

xref:req_perms[Appendix] defines precisely what permissions are required by available operations. 
Permissions may be granted as global or as group-scoped, i.e. valid only in the scope of
a specified group.

Permissions are assigned to an entity on the basis of three conditions (i.e. if an entity
meets required conditions it receives permissions). The specification of those 
conditions is called a policy. Every group can have it's own policy and there is also one
global policy. A policy is a set of pairs (condition, permissions). Possible conditions 
can be defined as: 

- *an attribute* - the most common way of defining a condition is to use an attribute. 
 In this case the permission is granted to individuals who possess the specified attribute.
 IMPORTANT (1): if the attribute contains values, then the permission is granted to
 everybody who possesses this attribute with at least one of the possible values. 
 If the attribute has no value, the permission is granted to everybody who has an attribute
 with the same name (with or without values - it is not relevant in this case).
 IMPORTANT (2): for global policies (see below) only global attributes are used to 
 evaluate the condition.
- *a member* - the member condition grants the permission to every member of the group 
 that the policy is assigned to. This condition will never be met when the accessed
 operation requires a global permission.
- *an owner* - the owner condition is the trickiest one. The permission is granted when
 an  entity that tries to perform an operation is also the subject of this operation. This
 is only possible in a limited number of operations, e.g. the caller of a
 isMember(subject, group) method can meet this condition if he/she is
 also the "subject" in parameters list.

A group's policy is established in the following way: 

- if the group has a policy set, then it is used. 
- if not then the parent group's policy is used (of course this is a recursive behaviour). 
- if the group is a top-level group (i.e. no parent) then the global policy is used
 as the group's policy. 

In short, group policies are inherited from parent groups and are not merged in
any way (the first found is used). When a UVOS operation is invoked it can
be authorized globally or, when the operation affects only a particular group, 
in the scope of the given group. In the first case only the global policy is used. 
In the second case the both a global policy is used together with the group's policy. 
There are no conflicts between global policy and the group's policy as the resulting 
permissions are always either the same or better as those coming from the individual ones. 

NOTE: even with group-scoped access, global attributes are still needed to get permissions 
that are granted by a global policy.

.Example: 
=============================================================================
Let's assume the following policies are defined:
 
- *Global Policy*: (member -> r), (owner -> rf), (Attribute 'superuser' -> rfiw)
- *Group /Math-VO Policy*: (member -> rf), (Attribute 'mathmanager' -> rfiw)
- *Group /Math-VO/Staff/Admins Policy*: (member -> rfiw)

With the above assumptions effective policies for the groups are as follows:

- *Group /Math-VO*: (member -> rf), (Attribute 'mathmanager' -> rfiw)
- *Group /Math-VO/Staff*: as above
- *Group /Math-VO/Staff/Admins*: (member -> rfiw)
- *Group /QSAR-VO*: (member -> r), (owner -> rf), (Attribute 'superuser' -> rfiw)

and those groups' policies are evaluated always together with global policy 
to establish what are caller permissions.
==============================================================================

Now we can present the detailed algorithm for making an authorization decision:

1. Let _P1_ be an empty policy and _EP_ be an empty permission set.
2. If an accessed operation is in the  scope of a group then set the policy _P1_
 to the policy for this group. If needed inherit the policy from parent groups, 
 remembering that the first parent's policy should be used. If no parent policy 
 is set then use _P1_ = _Global Policy_.
3. If the accessed operation is in a group scope check if caller is a member of
 this group. If so add all member permissions from _P1_ and global policy to _EP_.
4. If the accessed operation can be self (or owner) accessible, check if caller
 is accessing  herself. If this is true add all owner permissions from _P1_
 and global policy to _EP_.
5. Retrieve all global attributes of the caller and add them into a _GlobA_ set. 
 If the accessed operation is in a group scope then retrieve all group scoped
  effective attributes of the caller and add it to the _GroupA_ set.
6. If the accessed operation lies  in the scope of a group then find all 
 permissions, which are either present in _P1_ or result from _GroupA_ attributes
 and add them to _EP_.
7. Find all permissions resulting from _GlobA_ attributes and present in _Global 
 Policy_ and add them to _EP_.
8. Check if all permissions, required for the invocation are present in _EP_. 
 If yes then grant access, deny otherwise.


The simple (default) authorization scheme
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The above description shows that the authorization scheme in UVOS is powerful, 
but also complicated. This section presents a simple usage pattern, that should
be sufficient for most situations. UVOS administrator can, of course, deploy a
modified version of the pattern or even mix various authorization schemes on a per VO basis.

The fundamental idea is to use a separate special attribute that grants UVOS access permissions
(and is not used for external purposes) with a fixed authorization policy for all groups.

This special attribute's name is +urn:authz:intervo:vo+ and following values are meaningful for it:

- *read*: grants *r* permission,
- *fullRead*: grants *rf* permissions,
- *identityCtl*: grants *rfi* permissions,
- *write*: grants *rfiw* permissions (i. e. all permissions).

Only one (fixed) global authorization policy is used. It assigns the permissions defined
above to the holder of corresponding attribute's value(s). Note that this policy
becomes the policy for every group (by inheritance).

With the above rules authorization is managed in a simple way. It is controlled by assigning
the +urn:authz:intervo:vo+ attribute with proper values to the users. If there is a need
to give permission to all members of a group then the authorization attribute should be 
set as the group's attribute.

Additionally, the default global authorization policy grants *r* permission for any *group members*
in that group scope and *rfi* permissions for *owner access*. This allows members of a group to
access it and always allows to access self data.

The special care should be taken when assigning +urn:authz:intervo:vo+ attribute as a global
attribute - it will result in granting of corresponding permissions in all contexts (i.e. for
all groups and as global permissions).


VO registrations (applications)
-------------------------------

The UVOS system contains an interface which allows for storing and processing VO applications. 
The system is organised as follows:

- *VO application form* is used to specify  overall rules that its applications must obey. It also 
contains additional information about data presented to the applying user. Examples of 
included information are: a description, the group to which the application is connected etc.
- *VO application* is issued by the user who has already filled the form.
- *VO form administrator* (every application form can have its own administrator) processes 
and accepts or rejects the application.
 
The UVOS interface provides a possibility to store and modify both forms and applications. 
In addition, application processing is possible. It must be noted, however, that form rendering
and user's input processing is not available as a server's functionality. When needed, it 
can be achieved by using an additional component. Currently only one, *uvos-webapp* is available.
It provides a web interface which displays application forms.

Email notification
------------------

The 1.0 and 1.1 releases  of the UVOS were capable only of sending simple email notifications  
when VO application was submitted (to the application form administrator) and when
VO application was processed (to the requester).

Since the release of version 1.2 this functionality was greatly enhanced:

- It is possible to subscribe for notifications dynamically at runtime.
- Notifications can be sent as an effect of almost all management operations, which include
 adding a new group member, deleting an identity or even changing an attribute.
- Notifications can be group scoped, i.e. sent only if the event occurred in a
 scope of a particular group. E.g. VO administrator can register herself to get
 notifications when new identities are added to a specified group/VO.
- There are no limits on the number and configuration options and notifications 
 (notifications with many recipients are also supported).
 
The following operations issue notifications:

1. addGroup
2. removeGroup
3. copyGroup
4. addIdentity
5. addEquivalentIdentity
6. removeIdentity
7. setAttribute
8. removeAttribute
9. addToGroup
10. removeFromGroup
11. setIdentityStatus
12. purgeHistoricalData


[[usage_scenarios]]
UVOS usage scenarios
--------------------

There are several typical deployments in which UVOS can be used. We present them below.

PULL authorization
~~~~~~~~~~~~~~~~~~

In the so called "pull mode" service (e.g. grid execution server, Unicore/X in case
of UNICORE middleware) contacts UVOS server to obtain the attributes of a user  which tries
to use one of its services. 

The attributes received from UVOS server can be used for authorization (e.g. server's
policy may permit only those users which are in a certain UVOS group or possess some 
attributes). Also service may use received attributes for other purposes; for instance 
UNICORE can be configured to use a predefined (scoped) UVOS attribute as an
information about local UNIX account of the requester.  Attribute scope is used
to distinguish mappings for multiple servers.

The PULL mode is depicted on the picture below:

image::./uvos-pull.png[alt="PULL mode",align="center",scaledwidth="50%"]

Pull mode is transparent for grid users. However is more difficult for grid administrators 
to set up: every grid site must be correctly configured to use UVOS.


PUSH authorization
~~~~~~~~~~~~~~~~~~

In so called "push mode" user first contacts UVOS server on her/his own and receives
the list of possessed attributes in a signed assertion. Later this assertion can be
attached to the requests send to grid services. If the service trusts assertion issuer
(i.e. UVOS server which issued it) then it can use the attributes for authorization.
 
Note that user can ask UVOS server only for subset of owned attributes. In such a
case user can hide part of her/his identity or alter the execution (e.g. choosing
her/his the role to be used). The PUSH mode is presented on the picture below:

image::./uvos-push.png[alt="PUSH mode",align="center",scaledwidth="50%"]


Pull mode is more scalable in terms of server administration and easier to set up. 
However it requires more user interaction and thus is more suitable for advanced grid users.
 
Web portal authentication
~~~~~~~~~~~~~~~~~~~~~~~~~

UVOS can be used to authenticate web browser users. SAML 2.0 standard is used to achieve
this functionality. To enable it you will need additional web application which 
provides a WWW login page - it is called *uvos-webauthn* and is available in UVOS distribution. 

Details of this deployment can be reviewed in many places. E.g. see Wikipedia
article http://en.wikipedia.org/wiki/SAML_2.0 , section on Web Browser SSO Profile.
UVOS uses POST binding. For more detailed, technical description see SAML 2.0 core
specification, SAML 2.0 profiles and SAML 2.0 bindings documents. References
can be found on the aforementioned Wikipedia page. Also it is the same style as
Shibboleth 2.0 works (it was not tested but in principle it should be possible to 
use Shibboleth SP with UVOS).

