Skip to content

ESGF_Attribute_Service

Stephen Pascoe edited this page Apr 9, 2014 · 8 revisions
Wiki Reorganisation
This page has been classified for reorganisation. It has been given the category REVISE.
This page contains useful content but needs revision. It may contain out of date or inaccurate content.

ESGF Attribute Service

Overview

The ESGF Attribute Service (ATS) is a web service responsible for issuing two kind of assertions about users:

  • A limited amount of personal information (user first and last name, email)
  • Access control attributes that have been granted to the user by some registration authority

The ATS querying mechanism is based on the Security Assertion Markup Language (SAML): a client sends a SAML/XML request as the payload of a SOAP request carried over HTTP (see example request ), and receives a SAML/XML assertion as the payload of the SOAP/HTTP response (see example response ).

The ATS has an extension mechanism such that it can retrieve the user information from a pluggable back-end metadata storage (for example, a database). All that needs to be done is to implement a Java class (an attribute factory ) that creates objects holding the user attributes, from the information contained in the back-end storage.

ESGF_Attribute_Service.png

Download, Installation and Configuration

Normally, the ATS is installed via the standard ESGF Node installation script, when specified with the --idp flag. Nevertheless, the ATS can also be installed and configured as a standalone web application.

Check out the "esgf-security" module from the GIT distribution, and compile it, resulting in a war file in the dist/ subdirectory:

git clone git@esg-repo.llnl.gov:esgf-security.git
cd esgf-security
ant make_dist
ls -l dist/esgf-security.war

Deploy the war file to a pre-existing Tomcat installation following your favorite process, for example:

mkdir <TOMCAT_DIR>/webapps/esgf-security
cp dist/esgf-security.war <TOMCAT_DIR>/webapps/esgf-security/.
cd <TOMCAT_DIR>/webapps/esgf-security/
jar xvf esgf-security.war

Don't start Tomcat yet! By default, the ESGF ATS is configured to connect to the ESGF Node database, and reads the database connection properties (host, username and password) from the file /esg/config/esgf.properties. To test the system, you may want to start by running the ATS in demo mode , by connecting it to a fake pool of users that is stored in an XML configuration file (see ESGFusers.xml ). You can do so by using a trimmed-down Spring configuration file ( see XML file ) that instantiates an _ attribute factory _ that parses the aforementioned demo users XML file:

cd <TOMCAT_DIR>/webapps/esgf-security/WEB-INF/classes/esg/security/config/
cp application-context-specific.xml application-context-specific.xml-orig
cp application-context-specific-demo.xml application-context-specific.xml 

In a production environment, it is also strongly recommended to expose the ATS only through the SSL protocol: this will require editing the Tomcat server.xml file and define a secure port (typically, 8443 or 443) that references a java keystore (and a truststore for client authentication, if needed, see later discussion on white listing), for example:

    <Connector port="8443" SSLEnabled="true" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="want" sslProtocol="TLS"
               truststoreFile="/esg/certificates/esg-truststore.ts" truststorePass="*"
               keystoreFile="/esg/certificates/esg-datanode-rapidssl.ks" keystorePass="*" alias="tomcat"/>

Testing

After starting Tomcat, the ATS becomes available at the following URL:

http(s)://hostname:port/esgf-security/saml/soap/secure/attributeService.htm (for example: https://esg-datanode.jpl.nasa.gov/esgf-security/saml/soap/secure/attributeService.htm ).

Clicking on the link above in a browser will actually result in an HTTP 500 error, because the service URL can only be invoked via a POST request that includes a valid SAML/XML request. In a typical situation, that URL will be invoked via SOAP/HTTP by a program that is coded to submit a valid SAML/XML request.

For convenience, the web application comes with a handy user interface that can be used to submit valid requests to the ATS, and thus verify that it is working properly (see Figure below). This user interface is made available at the base URL of the web application:

http(s)://hostname:port/esgf-security/ (for example: https://esg-datanode.jpl.nasa.gov/esgf-security/ )

ESGF_ATS_form.png

The form text field is used to input a valid user openid, i.e. the openid of a user that is found in the back-end metadata storage (in the demo case, in the sample XML file). Clicking on "Submit" will send a valid SAML request to the ATS (see example request ), which will return a corresponding response (see example response ). You can input in the text form any of the user openids that are contained in the file ESGFusers.xml . Using a different OpenID will result in an _ Unknown Principle _ SAML response from the ATS.

Extension Points

The ATS can be configured to read the user metadata from a pluggable back-end storage. In order to do so, you must do the following:

  • Provide an implementation of the Java interface SAMLAttributeFactory that is specialized to your specific back-end storage, for example _ esgf.security.contributed. MyDatabaseSamlAttributeFactory _ . This implementation will be responsible for accepting a user's openid, reading the user attributes from the back-end storage, and using these attributes to populate an instance of the object _ SAMLAttributes _ , which is then returned to the caller. Several example factories are included in the code, specifically:

    • SAMLAttributeFactoryTrivialImpl: example factory that only knows of one user
    • SAMLAttributeFactoryLocalXmlImpl: the aforementioned demo factory that reads user from an XML file
    • SAMLAttributeFactoryDAOImpl: a production-level factory that reads the user attributes from the ESGF p2p Node database
  • Configure the Spring configuration file _ application-context-specific.xml _ to use your factory implementation, by replacing the contents of the bean named _ samlAttributefactory _ with the new class name, and any arguments needed for instantiation. For example:

        <!-- Example implementation that looks up user attributes in local XML file -->
        <bean id="samlAttributeFactory" class="esgf.security.contributed.MyDatabaseSamlAttributeFactory">
                <constructor-arg index="0"><value>my-db-url</value></constructor-arg>
                <constructor-arg index="1"><value>my-db-username</value></constructor-arg>
                <constructor-arg index="2"><value>my-db-password</value></constructor-arg>
        </bean>
    

White Listing

It is possible to configure the ATS such as it will only accept requests from a list of trusted clients (a _ white list _ ). To do so, you must do two things: establish mutual trust between the ATS and the client, and configure the ATS to recognize the client Distinguished Name. Specifically, you must:

* Configure Tomcat to listen on a secure SSL port ( _ <Connector port="8443"... _ ) 
* Configure Tomcat to use a java key store to send its certificate to the client ( _ keystoreFile="..." keystorePass="..." alias="..." _ ) 
* Configure Tomcat to accept a certificate from the client, if it is presented ( _ clientAuth="want" _ ) 
* Configure Tomcat to use a trust-store that must contain the CA that issued the client certificate ( _ truststoreFile="..." truststorePass="..." _ ) 
* Configure the client to trust Tomcat's certificate (the way you do this will depend on the client you are using) 
* Finally, enable the "whiteList" property in the Spring configuration file, and populate the whiteList content with the identity of the client 

In the demo example Spring configuration file , if the property _ whiteListCertificateProvider _ is uncommented, the ATS will accept requests only from a client with a trusted certificate and Distinguished Name equal to _ CN= https://esg- gateway.jpl.nasa.gov/myopenid/rootAdmin, OU=jpl- esg.jpl.nasa.gov, OU=ESG-JPL, O=ESG _ .

Clone this wiki locally