This module can be used as a library (by developers) but most notably it is a base of Unicore/X VO support. As configuration in both cases is quite similar we present both situations here.
In the following sections some of the configuration options require value of a VO/GROUP type. Whenever it is needed it should be written in the following way:
/VO[/group1[/subgroup2[...]]]
where elements in square brackets are optional. E.g. /Math/users denotes a group 'users' of a VO called 'Math'.
In case of Unicore/X there are three configuration files related to a VO setup. The most important one is by default conf/vo.config from the installation directory of Unicore/X (you can change it by defining a java property pl.edu.icm.uasvo.configFile). It holds generic VO configuration not related to Unicore/X -- most of things is configured there. This file options are described below.
To enable the VO subsystem certain settings are also required in the main uas.config file. You will have to define an appropriate Attribute Source. There are two UVOS-related Attribute Sources: one for each mode. You can add them both, only one or even use them multiple times. However note that in practice it may make sense to use two PULL Attribute Sources (if your site uses two UVOS instances) but it rather does not make sense to use more then one PUSH Attribute Source. You can leave default XUUDB Attribute Source if you wish to use classic UNICORE XUUDB and VO subsystem only for authorization attributes. It is even possible to use both XUUDB Attribute Source and VO Attribute Source with UUDB mapping turned on - then the order of sources and combining algorithm is important (see Unicore/X documentation for details). Please note that this features were introduced in the version 6.3.1.
Example with all three attribute sources. Local data from XUUDB (if exists) will override xlogin and role received from VOs (in any mode):
uas.security.attributes.order=SAML-PUSH SAML-PULL XUUDB # ... here xuudb configuration uas.security.attributes.SAML-PUSH.class=eu.unicore.uas.security.vo.SAMLPushAuthoriser uas.security.attributes.SAML-PUSH.configurationFile=conf/vo.config uas.security.attributes.SAML-PULL.class=eu.unicore.uas.security.vo.SAMLPullAuthoriser uas.security.attributes.SAML-PULL.configurationFile=conf/vo.config
The ZZZ.configurationFile configuration option is not necessary if you want to use the conf/vo.config file for both attribute sources (as conf/vo.config is a default configuration file). However this option is very important when you want to use more then one UVOS PULL attribute source, as it allows to use different configuration files for them.
When using both PUSH and PULL mode together you can disable PULL mode dynamically for those requests that contain pushed assertions only. See vo.pull.disableIfAttributesWerePushed configuration option.
Logging configuration is done by means of standard Unicore/X logging configuration file. See Main VO subsystem configuration file section for possible settings related to the VO subsystem.
Note that in Unicore/X there is a simple program which allows you to test VO Push setup. The application is called without arguments and is available in bin directory.
When using this module as a library it is configured in source code. However there is a possibility to use a Java properties file to create configuration objects (see pl.edu.icm.unicore.voutils.conf.PropertiesBasedConfiguration class). The section Main VO subsystem configuration file describe the valid properties which can be used in this file. Otherwise you have to provide implementation of an interface required in constructor of class you wish to use.
The main configuration file (usually conf/vo.config) can be used to configure both PULL and PUSH modes. The following three sections provide complete reference of available options.
General configuration section holds settings which are used for both modes, so you should always properly set them.
| Property name | Range of values | Default value | Description |
| vo.xloginAttribute | URI | urn:unicore:attrType:xlogin | Attribute used as Xlogin. For further explanations see UUDB Support. |
| vo.defaultXloginAttribute | URI | urn:unicore:attrType:defaultXlogin | Attribute used as a default XLogin. For further explanations see UUDB Support. |
| vo.roleAttribute | URI | urn:unicore:attrType:role | Attribute used as UNICORE role. For further explanations see UUDB Support. |
| vo.defaultRoleAttribute | URI | urn:unicore:attrType:defaultRole | Attribute used as a default UNICORE role. For further explanations see UUDB Support. |
| vo.group | VO/GROUP | "" | Optional scope which will limit the attributes which server accepts. Server will honour only attributes with exactly this scope or global (i.e. without scope set). |
| vo.uudb.group | VO/GROUP | "" | Defines a scope (i.e. group) where this machine's mappings of certificates to OS accounts names are stored. Note that this option is IGNORED if vo.group is defined. |
| vo.truststore | Name of keystore file | "" | Defines a truststore, with certificates (not corresponding CA's certificates!) of trusted VO services. Never use SSL truststore of UnicoreX for this purpose as it effectively turns off the whole authorization! It is used for push mode (assertions issued by untrusted VO services are ignored) and in pull mode when signature verification is enabled. |
| vo.truststoreType | PKCS12 or JKS | JKS | Type of VO truststore. |
| vo.truststorePass | string | Password of VO truststore. | |
| vo.localServerURI | URI | http://example.org:7777 | Should contain this server URI. It is REQUIRED if pull mode is enabled, and is used to identify this server to the VO service. In push mode it is used as this server actor's name (note that assertions in WS security element with no actor set are also used). |
| Property name | Range of values | Default value | Description |
| vo.pull.enable | true, false | false | Defines if pull mode should be enabled. |
| vo.pull.enableGenericAttributes | true, false | true | If you want to use VO service ONLY as a replacement of XUUDB (i.e. to store xlogin mappings and roles) and NOT to use it as a source of other authorization attributes set it to false. |
| vo.pull.voHost | host name or IP address | localhost | Address of SAML VO service host. Note that this server's CA cert must be present in Unicore/X truststore. |
| vo.pull.voPort | 1-65535 | 2443 | Port of SAML VO service. |
| vo.pull.voPath | URI path | "" | If using UVOS as a service you can leave this field empty. Otherwise specify correct path part of VO service URI. |
| vo.pull.cacheTtl | integer | 600 | Controls pulled attributes cache. Set to negative integer to disable the caching or to positive number - lifetime in seconds of cached entries. |
| vo.pull.verifySignatures | true,false | true | Additional security (except transport level which is always on) can be achieved by verification of signatures. The key which is used for verification must be present in vo.truststore. |
| vo.pull.verifySignatures.alias | string | "" | Alias used for signature verification (only if vo.pull.verifySignatures is true). |
| vo.pull.xlogin | true, false | false | Controls if mappings of certificates to local accounts should also be taken from the VO service. To enable this feature set this option to true and set the vo.group or vo.uudb.group property. |
| vo.pull.role | true, false | false | Controls if UNICORE roles should also be taken from the VO service. To enable this feature set this option to true and set the vo.group or vo.uudb.group property. |
| vo.pull.enableTrustDelegation | true, false | true | If you enable trust delegation support then attributes will be pulled on behalf of the caller (of course if he/she delegated his/her trust to this service). This is useful as then there is no need to add this server's identity to the VO service and assign read permissions to it (by default everybody can read her/his own data). |
| vo.pull.disableIfAttributesWerePushed | true, false | true | Whether pull mode should be skipped if user sent (or pushed) some attributes with the request. Note that to make this feature work PUSH mode must be enabled AND PULL authorization must be invoked AFTER PUSH authorization. |
| Property name | Range of values | Default value | Description |
| vo.push.enable | true, false | false | Defines if push mode should be enabled. |
| vo.push.xlogin | true, false | false | If this option is false then a pushed attribute which is mapped on Xlogin (i.e. in vo.xloginAttribute property) will be ignored. In another words users won't be allowed to choose local Xlogin manually. To enable this feature set this option to true and set the vo.group or vo.uudb.group property. |
| vo.push.role | true, false | false | If this option is false then a pushed attribute which is mapped on Role (i.e. in vo.xloginAttribute property) will be ignored. In another words users won't be allowed to choose local Role manually. To enable this feature set this option to true and set the vo.group or vo.uudb.group property. |
All components use log4j logging mechanism. All events are logged with unicore.security.vo prefix. Further logging category is either pull, push or common. Finally reporting class name is appended.
Example snippet of log4j configuration for logging all events for VO subsystem but only INFO and higher events for PUSH mode can be specified as follows:
log4j.logger.unicore.security.vo=TRACE log4j.logger.unicore.security.vo.push=INFO
