VOMS-API v3

This is the developers guide for the VOMS-API library. The following documentation applies to version 3.0.0 and following of the library. Documentation of previous versions of the library can be found in the VOMS-API page.

VOMS-API basically provides two set of functionalities:

• interaction with the VOMS administrative web interfaces, to programmatically manage a VOMS VO.
• interaction with the MyProxy repository and the VOMS service, to programmatically retrieve attributed user credentials.

The library assumes that MyProxy and VOMS services have been installed and configured as described in the DVOS Pre-installation steps.

This page is organised as follows. The "High Level Desing" section introduces the rationale of the library, as well as main public interfaces and classes. The "Usage Examples" section shows basic usage of the library, also describing relevant implementation details.

High Level Design

The VOMS-API library provides four interfaces to manage a VOMS VO, and a further interface to interact with MyProxy and VOMS, to retrieve user's credentials. Main interfaces and classes of the VOMS-API library are shown in the following diagram, and briefly described below.

All interfaces and classes are relative to the root package of the library, i.e. org.gcube.vomanagement.vomsapi. It has been omitted in the following list to improve text readability.

• CredentialsManager - This interface contains operations to retrieve credentials for gCube users. Two types of credentials can be retrireved: plain credentials and attributed credentials. Plain credentials does not contains any user role, while attributed credentials contains the set of roles held by the user in the given VOMS group.
• VOMSAdmin - This interface contains methods to manage users, roles and groups of a VOMS VO.
• ExtendedVOMSAdmin - This interface contains additional utility methods to administer a VOMS VO. Methods of this interface delegates to those provided by the VOMSAdmin interface for the VOMS interaction.
• VOMSAttributes - This interface contains operations to manage attributes in a VOMS VO.
• VOMSACL - This interface contains operations to manage Access Control Lists in a VOMS VO.
• impl.VOMSAPIConfiguration - Instances of this class contains the configuration properties to interact with VOMS and MyProxy services. The set of configuration properties supported by the VOMS-API library are declared in the impl.VOMSAPIConfigurationProperty enum.
• impl.VOMSAPIConfigurationProperty - This enumeration contains the set of properties supported for the configuration of the VOMS-API library, see the the VOMS-API v3 Configuration page for details.
• impl.VOMSAPIFactory - Instances of this class creates stub objects to interact with VOMS and MyProxy services. Each VOMSAPIFactory is initialized with an instance of VOMSAPIConfiguration.
• impl.ssl.MySSLSocketFactory - This class provides an Axis compatible SSL socket factory that enables the usage of the VOMS-API library from a standalone java application (see the next subsection for details).

Standalone Java client and gHN support

The VOMS-API library can be used both from a standalone java client, both from a gCube Running Instance, hosted in a gHN container. This distinction is relevant, as, depending on the case, credentials used to interact with VOMS and MyProxy services must be differently managed.

To distinguish among these usage, the RUNS_IN_WS_CORE configuration property has been introduced. Setting the property to true will cause the library to set credentials in stubs accordingly to the Java-Ws-Core behaviour. Otherwise, setting it to false, will cause the library to use a custom code, contained in the org.gcube.vomanagement.vomsapi.impl.ssl package, to manage secure connections to VOMS and MyProxy services.

WARNING: In the second case, i.e. the standalone java client usage, the library will replace the standard Axis SSL socket factory with a custom factory. The custom factory synchronizes the creation of SSL sockets, to avoid concurrency issues derived from a multi-thread usage of the library. This is achieved setting the "org.apache.axis.components.net.SecureSocketFactory" axis configuration property. This setting will also influence all SSL connections made from the standalone java application.

Usage Examples

Configure the library

To succesfully interact with a VOMS (or MyProxy) service, an object representing VOMS (or MyProxy) stubs must be configured and used. VOMS-API provides a factory to get VOMS and MyProxy stubs, the factory is implemented by the VOMSAPIFactory class.

The factory can be initialized supplying a configuration object, i.e. an instance of the VOMSAPIConfiguration class. An instance of this class can be created in three different ways:

1. using the default configuration file,
2. using a custom configuration file and
3. programmatically.

Here below are three examples showing the use of each method. In all three cases, the file (or the properties object) must contain properties described in the VOMS-API v3 Configuration page.

Default configuration file

This configuration uses the default configuration file, i.e. the VOMS-API.properties file in the current working directory.

VOMSAPIFactory factory = new VOMSAPIFactory(new VOMSAPIConfiguration());

In this case, a zero argument constructor is also provided for the impl.VOMSAPIFactory. It instantiates a new VOMSAPIConfiguration object internally. This makes the creation of the factory even easier:

VOMSAPIFactory factory = new VOMSAPIFactory();

The configuration object in use can always be retrieved using the getVOMSAPIConfiguration() method of the factory.

NOTE: The static method VOMSAPIConfiguration.setDefaultConfigurationFile(...) can be used to change the name of the default configuration file the VOMS-API library looks for.

Custom configuration file

This configuration uses a custom configuration file that must be passed to the VOMSAPIConfiguration constructor, as in the example below.

VOMSAPIFactory factory = new VOMSAPIFactory(new VOMSAPIConfiguration(new File("myConfigurationFile.props")));

Programmatic configuration

Using the programmatic configuration, a Properties object must be passed to the VOMSAPIConfiguration constructor, as in the example below.

import org.gcube.vomanagement.vomsapi.impl.VOMSAPIConfigurationProperty;
 
...
 
java.util.Properties props = new Properties();
props.setProperty(VOMSAPIConfigurationProperty.VOMS_HOST.toString(), "voms.research-infrastructures.eu");
props.setProperty(VOMSAPIConfigurationProperty.VO_NAME.toString(), "gCube");
props.setProperty(VOMSAPIConfigurationProperty.CLIENT_CERT.toString(), "/path/to/your/cert.pem");
props.setProperty(VOMSAPIConfigurationProperty.CLIENT_KEY.toString(), "/path/to/your/key.pem");
props.setProperty(VOMSAPIConfigurationProperty.CLIENT_PWD.toString(), "yourPassword");	
VOMSAPIFactory factory = new VOMSAPIFactory(new VOMSAPIConfiguration(props));

Configuring Credentials

Credentials used to contact VOMS can be configured both at the creation of the VOMSAPIConfiguration object, as described above, both at later time. Current credentials are kept in the VOMSAPIConfiguration object, and set independently for each VOMS invocation. Thus, changing them will affect all invocations to VOMS made from stubs that share the same VOMSAPIConfiguration instance.

Properties to intially configure credentials in the VOMSAPIConfiguration are described in the VOMS-API v3 Configuration page. The following method can be used to programmatically change credentials used by a VOMSAPIConfiguration instance:

VOMSAPIConfiguration.setCredentials(ExtendedGSSCredential credentials)

NOTE: This setting will affect all stubs generated from factories that have been initialized using that VOMSAPIConfiguration instance.

Interact with VOMS

Once created and configured, the VOMSAPIFactory instance can be used to retrieve VOMS stub interfaces. The following subsections show describes the usage of the VOMSAdmin, ExtendedVOMSAdmin and VOMSAttributes interfaces. Some examples are also provided.

The VOMSAdmin and ExtendedVOMSAdmin interfaces

The following example shows some usage of the VOMSAdmin and ExtendedVOMSAdmin interfaces:

import org.glite.wsdl.services.org_glite_security_voms.User;
import org.gcube.vomanagement.vomsapi.VOMSAdmin;
 
...
 
String userDN = "/C=IT/O=INFN/OU=Personal Certificate/L=ENGINEERING RDLAB/CN=Alice";
String userCA = "/C=IT/O=INFN/CN=INFN CA";
 
User user = new User();
user.setDN(userDN);
user.setCA(userCA);
user.setCN("Alice");
user.setMail("user.mail@domain.org");
 
//create stub
VOMSAdmin admin = factory.getVOMSAdmin();
 
//create a new user
admin.createUser(user);
 
//create a new role
admin.createRole("myRole");
 
//add the user as a member of a group
admin.addMember("/gCube/devsec", userDN, userCA);
 
//assign the role to the user in the group
admin.assignRole("/gCube/devsec", "myRole", userDN, userCA);
 
//list users
User[] users = factory.getExtendedVOMSAdmin().listUsers();

In a similar way other VOMS operations can be used to query and manage the VOMS VO.

NOTE: Unless differently noted, in stub methods group names are absolute to the VO, e.g: /testVO/testGroup1/testGroup2. In addition, roleName arguments does not requires the "Role=" prefix, as well as role returned from stub methods are already cleaned from the "Role=" prefix. Moreover, in all methods returning an array, if the return contains no elements, an empty array is returned, instead of the null value.

The VOMSAttributes interface

The VOMSAttributes interface requires some more description, as the use of VOMS attributes is not very intuitive.

Basically, VOMS attributes are organized in classes, where each class of attribute defines the attribute name, a class description, and a further boolean property named "uniqueness". Attribute instances are then created from an existing attribute class. Each attribute instance is defined by its class and its value, and can be assigned to users, groups and roles of the VOMS VO. Attributes in VOMS are single value, i.e. the same attribute can only be assigned once to the same user, group, or role.

The uniqueness property of a class defines if two instances of that attribute class can (or cannot) have the same value in the VO. More specifically, if a class has been defined "unique", by setting the uniqueness property to true at class definition, then each new attribute instance of that class will need a different value from those already defined. Otherwise, if the uniqueness value has been set to false (the default), the uniqueness check will not be enforced, and attribute instances with the same value can be defined in the VO.

The following code shows how to create a new attribute class, and how to assign a new attribute value to a user.

import org.glite.wsdl.services.org_glite_security_voms_service_attributes.AttributeClass;
import org.glite.wsdl.services.org_glite_security_voms_service_attributes.AttributeValue;
import org.gcube.vomanagement.vomsapi.VOMSAttributes;
 
...
 
//create the VOMSAttribute stub
VOMSAttributes attributes = factory.getVOMSAttributes();
 
//create the attribute class
attributes.createAttributeClass("yourAttributeClass", "your attribute description");
 
//get the attribute class reference		
AttributeClass existingClass = attributes.getAttributeClass("testAttributeClass");
 
//create a new attribute instance
AttributeValue value = new AttributeValue(existingClass, "ignored", "testValue");
 
//set the attribute instance to a user		
attributes.setUserAttribute(user, value);
 
//list attributes of the user
attributes.listAttributeClasses();
 
//list all attribute classes
attributes.listUserAttributes(user);

NOTE: Current VOMS implementation does not allows to change the description and the uniqueness property of an attribute class already defined.

Create and retrieve user credentials

Besides VOMS VO administration, the VOMS-API library also provides functionalities to create and retrieve user credentials. In particular, the CredentialsManager interface contains some methods to retrieve credentials from a MyProxy repository, and to add VOMS attributes, like roles, that have been assigned to the user in the VOMS VO. Two set of methods have been implemented: getPlainCredentials() and getAttributedCredentials(). Both methods are overloaded to work for the OnlineCA, and for the MyProxy repository, as described below.

Retrieve plain user credentials

The getPlainCredentials() methods allows to retrieve plain, i.e. without VOMS attributes, credentials from a MyProxy repository. Parameters identifying the MyProxy service (as hostname and port) can be supplied in the VOMS-API configuration, see the VOMS-API v3 Configuration page.

The method has been overloaded to enable the use of the OnlineCA coupled with the MyProxy repository. In this case the password to retrieve user credentials is not needed, and the retrieval operation is authenticated using credentials configured in the VOMSAPIConfiguration object. Otherwise, to retrieve credentials stored in the MyProxy repository with an username and password, the two argument method can be used.

The following example shows how to retrieve plain credentials from a MyProxy instance. In this example configuration parameters of the MyProxy repository are supplied programmatically, but the properties file configuration is also supported.

import java.util.Properties;
import org.gcube.vomanagement.vomsapi.CredentialsManager;
import org.gcube.vomanagement.vomsapi.impl.VOMSAPIFactory;
import org.gcube.vomanagement.vomsapi.impl.VOMSAPIConfiguration;
import org.gcube.vomanagement.vomsapi.impl.VOMSAPIConfigurationProperty;
 
...
 
Properties props = new Properties();
props.setProperty(VOMSAPIConfigurationProperty.CLIENT_CERT.toString(), "/path/to/your/cert.pem");
props.setProperty(VOMSAPIConfigurationProperty.CLIENT_KEY.toString(), "/path/to/your/key.pem");
props.setProperty(VOMSAPIConfigurationProperty.CLIENT_PWD.toString(), "yourPassword");
props.setProperty(VOMSAPIConfigurationProperty.MYPROXY_HOST.toString(), "grids04.eng.it");
 
//create the stub factory
VOMSAPIFactory factory = new VOMSAPIFactory(new VOMSAPIConfiguration(props));
 
//create CredentialsManager stubs
CredentialsManager credManager = factory.getCredentialsManager();
 
//create plain credentials (from the MyProxy online CA)
ExtendedGSSCredential creds = credManager.getPlainCredentials("yourUserName");
 
//create plain credentials (from the MyProxy repository)
ExtendedGSSCredential creds = credManager.getPlainCredentials("yourUserName", "yourPassword");

Retrieve attributed user credentials

As far as the getAttributedCredentials() are concerned, the code is similar to the example above, but retrieved credentials will also contains all roles of the user in the VOMS group passed as parameter.

[Example to be added]