Difference between revisions of "How To use VOMS api library"

Revision as of 17:57, 16 November 2007

Package Installation

Download

The VOMS api library can be downloaded from here.

Installation Procedure

The following steps have to be performed in order to use this library:

• uncompress the org.diligentproject.dvos.voms-api.SERVICEARCHIVE-0.4.0-0.tar.gz file
• copy dvos.voms-api.jar in a convenient directory
• Edit a vomsAPI.properties file based on the template provided in the SA.
• Move your vomsAPI.properties in client working directory in order to use the settings chosen.

Using VOMS API library

To succesfully contact the VOMS service with VOMS api library you need to use a VOMS servlet.

Create servlet credentials

VOMS servlet needs valid credentials, registered in the VOMS and associated to the VO-Admin role. This is required as the servlet needs to create users, groups and roles in the VOMS service.

These credentials needs to be converted in a PKCS12 format to be loaded by the servlet. Starting from valid credentials in PEM format (usually host credentials can be used for this purpose) you need to issue this command to convert it to PKCS12 format:

openssl pkcs12 -export -in <path_to_the_hostcert.pem> -inkey <path_to_the_hostkey.pem> -out <output_file.p12>

This will create a new (password protected) file containing both the certificate and the private key. We'll use the file and the password later in the service configuration.

The servlet also needs to trust the certificate of the VOMS service, to this purpose a Java truststore containing the VOMS certificate must be created. To create one you can simply issue this command:

keytool -import -alias <name> -file <path_to_VOMS_cert.pem>  -keystore <path_to_your_trustStore_file>

The alias is simply a string to identify the certificate you're importing in the truststore. If the trsustore file does not exists it will be created. For instance if you want to import the grids13.eng.it certificate in the trsutstore you have to issue:

keytool -import -alias grids13 -file /etc/grid-security/vomsdir/grids03.eng.it-diligent.pem  -keystore certs/VOMSServlet.trustStore

To list certificates stored in the trustStore:

keytool -list -v -keystore <path_to_your_trustStore_file>

Here you can find further information to manage a trustStore.

Install and configure the VOMS servlet

Shutdown tomcat if it is already running. Download the new version of VOMSServlet.war file from the ENGrepository. Deploy it in a tomcat container previously installed as described here.

Once deployed the servlet needs to be configures to point to the right VOMS installation. You can do this editing the $CATALINA_HOME/webapps/VOMSServlet/WEB-INF/web.xml file. Following parameters must be set:

     <!-- the host name of the VOMS Admin interface -->
     <init-param>
	<param-name>hostName</param-name>
	<param-value>https://grids13.eng.it:8443/voms/diligent/services/VOMSAdmin</param-value>
     </init-param>

     <!-- the pcks12 certificate -->
     <init-param>
	<param-name>keyStore</param-name>
	<param-value>output_file.p12</param-value>
     </init-param>

     <!-- the keystore type -->
     <init-param>
	<param-name>keyStoreType</param-name>
	<param-value>PKCS12</param-value>
     </init-param>

     <!-- the password of the specified keyStore --> 
     <init-param>
	<param-name>keyStorePassword</param-name>
	<param-value>pkcs12_password</param-value>
     </init-param>

     <!-- the path to a trustStore --> 
     <init-param>
        <param-name>trustStore</param-name>
        <param-value>path_to_your_trustStore_file</param-value>
     </init-param>	

     <!-- the password of the specified keyStore --> 
     <init-param>
        <param-name>trustStorePassword</param-name>
        <param-value>truststore_password</param-value>
     </init-param>	
	
     <!-- the truststore type -->		
     <init-param>
         <param-name>trustStoreType</param-name>
         <param-value>JKS</param-value>
     </init-param>

In order to enable interoperation between the VOMS servlet and the VOMS service the certificate used by the servlet (that in pkcs12 format) must be registrered in the VOMS and associated to the VO-Admin role. This is required as the servlet needs to create users, groups and roles in the VOMS service.