>>> DESCRIPTION


This project contains a web application that can be used to deploy an ESG Attribute Service and/or an ESG Authorization service.
Additionally, the packaged jar contains ESG utilities for parsing and producing SAML statements that can be used in other ESG SAML-aware projects.

git remote add upstream https://git@github.com/ESGF/esgf-security.git


>>> PREREQUISITES

o Fairly recent distribution of Ant: 1.7+

o Java 1.6 or above.

o Optional: Ivy installed as Ant extension. 
When running from the command line, this means installing the Ivy jar into the ant lib/ directory.
To run the Ant tasks within an Eclipse environment (because Eclipse comes packaged with its own version of Ant), 
the Ivy jar must be copied into the Eclipse-specific Ant lib directory, or into the user's ~/.ant/lib directory.

>>> INSTALLING AND BUILDING FROM THE COMMAND LINE

After downloading the module from the ESGF GIT repository, cd to the top-level module directory and run ant:

cd esgf-security

ant make_dist
will create the jar and war files in the dist/ subdirectory.

ant test 
will run the tests.

>>> INSTALLING WITHIN ECLIPSE

This module is configured to be interpreted as both a Java and Dynamic Web Project by Eclipse
(after it has been compiled from the command line, so that all the jar dependencies are downloaded by Ivy).
Note that in order to run the web application from within the Eclipse (i.e. without deploying the war file
to a separate servlet container), you must first run the "make_web_dir" ant task, which will assemble
the Eclipse WebContent/WEB-INF directory from source files, configuration files and libraries found in the
module distribution, then instruct Eclipse to "refresh" the content directory for the project.


>>> CONFIGURING AND RUNNING THE WEB APPLICATION

Deployment of the web application is controlled by the file esg/security/config/application-context-specific.xml (in the src folder): 
comment out whichever service stack is not going to be deployed.

Assuming that the servlet container is started on localhost on ports 8080/8443, and that the application is deployed at the "esgf-security" context, 
the services are available as follows:

1) ESG Attribute service

1a) non-secure URL endpoint: http://localhost:8080/esgf-security/saml/soap/secure/attributeService.htm
    Run the client esg.security.attr.main.SAMLAttributeServiceSOAPClient to execute a test query.
    
1b) secure URL endpoint: https://localhost:8443/esgf-security/saml/soap/secure/attributeService.htm
    First follow the steps to setup mutual authentication (see below),
    then run the client esg.security.attr.main.SecureSAMLAttributeServiceSOAPClient to execute a test query.

Note that by default, the ESG Attribute Service uses the class SAMLAttributeFactoryTrivialImpl which is a trivial implementation of SAMLAttributeFactory
that returns valid attributes only for a user identifier equal to "Test Openid". To use the service in conjunction with a specific
user attribute repository, create your own implementation of SAMLAttributeFactory and deploy it in the Spring context
as a bean named "samlAttributeFactory" (replacing SAMLAttributeFactoryTrivialImpl in application-context-specific.xml).

2) ESG Authorization Service

2a) non-secure URL endpoint: http://localhost:8080/esgf-security/saml/soap/secure/authorizationService.htm
    Run the client esg.security.authz.main.SAMLAuthorizationServiceSOAPClient to execute a test query.
    
2b) secure URL endpoint: https://localhost:8443/esgf-security/saml/soap/secure/authorizationService.htm
    First follow the steps to setup mutual authentication (see below),
    then run the client esg.security.authz.main.SecureSAMLAuthorizationServiceSOAPClient to execute a test query.

Note that the SAML Authorization Service uses the class SAMLAuthorizationFactoryTrivialImpl which is a trivial implementation of SAMLAuthorizationFactory
that returns valid authorizations only for the test user identifier "Test Openid" (for all resources and actions). 
To use the service in conjunction with a specific authorization repository, create your own implementation of SAMLAuthorizationFactory 
and deploy it in the Spring context as a bean named "samlAuthorizationFactory" (replacing SAMLAuthorizationFactoryTrivialImpl in application-context-specific.xml).


>>> HOW TOP SETUP MUTUAL AUTHENTICATION

In order to setup mutual authentication (and optional white-listing) between the client and server, the following steps must be followed:

server side:

- configure the Tomcat connector in server.xml to:
	- listen on a secure port (e.g. 8443)
	- use a keystore certificate (test certificate provided in distribution: server-cert.ks)
	- use the client certificate, if found (clientAuth="want")
	- mandate service non-secure endpoint (e.g. 8080) to redirect to service secure endpoint (e.g. 8443)
	For example:
	<Connector SSLEnabled="true" clientAuth="want" keystoreFile="/Users/cinquini/myApplications/apache-tomcat/server-cert.ks" maxThreads="150" port="8443" protocol="HTTP/1.1" scheme="https" secure="true" sslProtocol="TLS"/>
	
- configure Tomcat to use a trustore that contains the CA that issues the client certificate. 
  For example, start Tomcat with these options:
  -Djavax.net.ssl.trustStore=/Users/cinquini/myApplications/apache-tomcat/esg-truststore.ts -Djavax.net.ssl.trustStorePassword=changeit

- optionally, configure the server with a white list that include's the client's certificate subject

client side:
- obtain a valid certificate in keystore format from your CA
- configure the client to use a trustore that contains the service's certificate (example provided in distribution: client-trustore.ks)

>>> TECHNICAL NOTES

o To allow flexibility in deployment (specifically, the capability of replacing the attribute and authorization factory implementations),
the Spring beans for each service are auto-wired by name, but not auto-deployed in the Spring context. 
Currently the URL end-points for the Spring controllers are set as fixed request mappings in the Java classes and cannot be changed.

o This project requires Java 1.6 because of faulty XML libraries in Java 1.5 and below. 
Alternatively, if running with Java 1.5, the correct XML libraries can be placed in the JVM endorsed directory.
For convenience, the ant task "make_endorsed" can be run to download all the required jars in the subdirectory lib/endorsed.
These jars then need to be copied into the Java 1.5 endorsed directory.