View source for EMI Argus-EES test plan

This test plan is following the [https://twiki.cern.ch/twiki/bin/view/EMI/EMITestPlan EMI SA2 template].

== EES Test Plan ==

=== Service Description ===

The EES is a daemon that acts as an '''obligation transformer''' for requests to the PEPd. The EES takes SAML2-XACML2 authorization request messages as input. The EES takes the local site policy into account to '''transform''' the incoming request. The EES will start a new execution thread and apply the defined policy to the incoming request.

More information on the [[EES]].

=== Yum Installation ===

To install the EES configure the YUM-based EPEL and EMI repositories. The IGTF distribution can also be done through a YUM-based repository, including the [[FetchCRL3]] utility to refresh the CA CRLs. Note that the need for the IGTF distribution depends on the set of configured EES plugins.

The EES depends directly on:
* SAML2-XACML2-C-LIB
* (g)libc

EES configurations specify plugins which operate on the incoming request. The EES ships with a '''transformer''' plug-in, which is used to unpack the XACML obligations from the PDP response. This is needed since they are merged into the PEPd request and subsequently sent to the EES by the EES obligation handler (living inside the PEPd).

Install the '''EES''' service by performing: yum install ees

This will install the package '''ees''' which will pull in the following packages:
* ees
* xacml (called saml2-xacml2-c-lib for EMI-1)

Install the '''EES''' obligation handler by performing: yum install ees-pepd-oh

This will install the package '''ees-pepd-oh''' which will pull in the following packages:
* argus-pep-server
* java

This is the first release of the EES service and the EES obligation handler in EMI. There is nothing to upgrade from.

== System tests ==

=== Test setup EES ===

First we install and setup the system for testing. This means to prepare the system taking a clean CentOS 5 or Scientific Linux 5 machine as a baseline. 
 yum install ees

If there is no ees useraccount yet, create it
 useradd -r ees

Start the ees service
 /etc/init.d/ees start

The basic installation is now done.
We can now test the basic functionality of the EES by using the following script.
Note that it uses nc which can be installed using: yum install nc

<pre>
#!/bin/bash

# Configuration
host=0.0.0.0
port=6217

MSG='<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:XACMLcontext="urn:oasis:names:tc:xacml:2.0:context:schema:os" xmlns:XACMLassertion="urn:oasis:names:tc:xacml:2.0:profile:saml2.0:v2:schema:assertion" xmlns:XACMLpolicy="urn:oasis:names:tc:xacml:2.0:policy:schema:os" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" xmlns:XACMLService="http://www.globus.org/security/XACMLAuthorization/bindings" xmlns:XACMLsamlp="urn:oasis:names:tc:xacml:2.0:profile:saml2.0:v2:schema:protocol" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
<SOAP-ENV:Body>
<XACMLsamlp:XACMLAuthzDecisionQuery CombinePolicies="true" ReturnContext="true" InputContextOnly="false" IssueInstant="2010-03-25T14:55:01Z" Version="2.0" ID="ID-1804289383">
<saml:Issuer xsi:type="saml:NameIDType" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName">NetCat</saml:Issuer>
<XACMLcontext:Request xsi:type="XACMLcontext:RequestType">
<XACMLcontext:Action xsi:type="XACMLcontext:ActionType">
</XACMLcontext:Action>
</XACMLcontext:Request>
</XACMLsamlp:XACMLAuthzDecisionQuery>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
'

# Takes three args, a test string and a pattern to match to
test_main() {
  output=`echo -n "$1" | nc -n -i1 $host $port | grep -w "$2"`
  if [ -z "$output" ]
  then
    echo "ERR"
  else
    echo "OK"
  fi  
}

echo -en "Basic sanity test\t"
test_main "$MSG" "200 OK"
echo -en "Basic failure test\t"
test_main "<TEST>" "500 Internal"
</pre>

Expected result:
<pre>
(testuser@ees.testmachine:~) ./ees_test.sh 
Basic sanity test       OK
Basic failure test      OK
</pre>

=== Test setup EES Obligation handler ===

==== EES preparation ====

The default '''/etc/ees.conf''' configuration file will contain the EES transformer plugin which is able to decode obligations from incoming XACML requests. Here is a '''ees.conf''' snippet which loads the transformer plug-in:

  # plug-ins
    transformer        = "ees_plugin_transformer.mod"
    good               = "ees_dummy_good.mod"
  # policies
  transformer:
    transformer -> good

To test integration in the Argus PEPd, configure the EES OH in the pepd.ini configuration file.

==== PEPd preparation ====
Install the OH plug-in .jar file by running on the PEPd (argus-pep-server) service node:
 yum install ees-pepd-oh
This will install it into /var/lib/argus/pepd/lib/ or equivalent PEPd library directory.
Configure the PEPd to use the EES OH and specify the url of a running EES instance. Here is a '''pepd.ini''' snippet:
  [SERVICE]
  ...
  obligationHandlers = EES_OH
  ...
  [EES_OH]
  ENDPOINT = http://ees_instance:6217/
  parserClass = org.glite.authz.pep.obligation.eesmap.EESObligationHandlerConfigurationParser

Restart the pepd:
 /etc/init.d/argus-pepd restart

which should result in output in the pepd process log 
 2011-04-10 12:43:21.420Z - INFO [IniOHConfigurationParserHelper] - Loading Obligation Handler EES_OH
 2011-04-10 12:43:21.421Z - INFO [EESObligationHandlerConfigurationParser] - EES Obligations sent to endpoint: http://ees_instance:6217/
 2011-04-10 12:43:21.421Z - INFO [EESObligationHandlerConfigurationParser] - Starting new EES OH
 2011-04-10 12:43:21.428Z - INFO [EESObligationHandler] - Loading EES OH!
 2011-04-10 12:43:21.428Z - INFO [IniOHConfigurationParserHelper] - Added obligation handler: EES_OH

=== Basic functionality tests (manual) ===
Configure [[gLExec]] to use the '''lcmaps-plugins-c-pep''' plug-in and the dummy plug-in from the '''lcmaps-plugins-basic''' plug-ins. Configure the C-PEP plug-in to connect to your running PEPd instance and configure the '''LCMAPS good''' plug-in to map to the 'nobody:nobody' account:
<pre>
# where to look for modules
path = /usr/lib64/modules

# module definitions
good = "lcmaps_dummy_good.mod"
       " --dummy-username nobody"
       " --dummy-group nobody"
       " --dummy-sec-group nobody"

pepc = "lcmaps_c_pep.mod"
       "--pep-daemon-endpoint-url https://argus.testbed:8154/authz"
       " -resourceid http://authz-interop.org/xacml/resource/resource-type/wn"
       " -actionid http://glite.org/xacml/action/execute"
       " -capath /etc/grid-security/certificates/"
       " -pep-certificate-mode implicit"

glexec_get_account:
pepc -> good
</pre>
The expected result is a account mapping by gLExec to the user 'nobody:nobody' account.
This can be verified by running the following command and verifying activity by the PEPd and the EES by tailing their log files. 
 (user@testmachine:~) /usr/sbin/glexec /usr/bin/id -a
 uid=99(nobody) gid=99(nobody) groups=99(nobody)
The gLExec/LCMAPS syslog output will be something like
 Apr 10 15:21:11 genome3 glexec[11844]: lcmaps_plugin_c_pep-plugin_run(): found dn: /O=dutchgrid/O=users/O=nikhef/CN=My First Grid Certificate
 Apr 10 15:21:24 genome3 glexec[11844]: 2011-04-10.13:21:11Z-11844 : lcmaps_plugin_c_pep-plugin_run(): C-PEP plugin succeeded

For the PEPd '''/var/log/argus/pepd/process.log''' should provide detailed information on the incoming authorization requests if the loglevel has been sufficiently raised in '''/etc/argus/pepd/logging.xml''' (loglevel 'ALL' is useful here). It will contain a reference to the EES similar to:
 2011-04-10 13:20:33.521Z - DEBUG [EESObligationHandler] - Starting transfer to EES

The EES will log to syslog (usually '''/var/log/messages''') and must provide basic information on the incoming authorization requests, similar to:
 Apr 10 15:21:24 ees_instance ees: setAttributeIssuer(), tried to set NULL issuer 
 Apr 10 15:21:24 ees_instance ees: Running plugin ees_plugin_transformer.mod 
 Apr 10 15:21:24 ees_instance ees: Running transformer 
 Apr 10 15:21:24 ees_instance ees: Running plugin ees_dummy_good.mod

=== Performance tests ===
Using '''ab''', the Apache benchmarking tool, the EES performance can be benchmarked.
Create a request.xml containing a typical XACML request (similar to the excerpt shown in the automated functionality test script) and invoke ab.
  ab -n 1000 -c 100 -p ~/request.xml http://ees_instance:6217/

You should see something like this (or better)
  Requests per second:    272.75 [#/sec] (mean)
  Time per request:       366.632 [ms] (mean)

=== Regression tests ===
Not applicable