= Resource Provider AAA Guide =
== AAA overview ==
Access control is an optional service on the SENSEI test platform. Each public interface in the system can be access controlled or not, at the owner's discretion. 
Two basic components are required in the system to enable access control:
* an identity provider, which in the SENSEI architecture is a Security Token Service
* an access control decision making function, which in the SENSEI architecture is a AAA block

[[PageOutline(2-3,Table of Contents,inline)]]

== Choosing the form of access control ==
Access control in SENSEI can be done on the basis of the user's privileges, or on the basis of payment. This choice is made by the resource provider. If the access control should be performed based on payment, the REP should be registered with a payment based AAA service. Instructions for this can be found [[wiki:PrivacyAndBilling|here]].
If the access control should be performed based on privileges, the REP should be registered with a privilege based AAA service. Instructions for this can be found below.

== Deployment of a AAA enabled REP ==
A deployable AAA enabled REP is provided for testing purposes. This REP is designed to exercise the AAA functions and comes with an integrated synthetic sensor producing random values, as a proof of concept. AAA functionality should be added to operational REPs, based on the specification provided [wiki:trt-war here]. This is a developer concern, and is therefore not described further here.
=== Getting the software components ===
* Apache Tomcat servlet container or equivalent
Instructions for setting up Apache Tomcat can be found [http://tomcat.apache.org/tomcat-6.0-doc/setup.html here].
* STS WAR file
The STS WAR file can be downloaded from here: [wiki:trt-war AAA downloads page].
The WAR files should be first configured for the deployment setup (see below) and then deployed in the servlet container. For Tomcat, instructions are provided [http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html here] (see in particular the "Deployment on Tomcat startup" section).
=== Configuration ===
The WAR file contains one file which need configuring to run correctly on the target deployment platform. Each field requiring a deployment specific value has been identified with the string "REPLACE:". Other fields have been set to typical defaults which should satisfy most deployments. These can however be modified for advanced tuning of the AAA service. For more information contact TRT (UK).
The WAR file is an archive containing object code, presentation templates and configuration files. The downloaded WAR file should therefore be opened (e.g. using [http://www.7-zip.org/ 7-zip]) to edit the following configuration file:
* rep.war/WEB-INF/classes/messages.properties
||= '''Field''' =||= '''Expected content''' =||
||rep.id||The identifier of the REP, which should be the URL of this REP||
||aaaservice.uri||The URL of the AAA Service which will provide access control decisions||
||resDir.uri||The URL of the SENSEI resource directory||

== Setting access policies ==
=== Writing policies ===
First a set of policies must be defined to specify the access rules which should apply. These are specified in a text file with the .drl extension.
For the enthusiasts, a full description of the rules language can be found [[http://downloads.jboss.com/drools/docs/5.1.1.34858.FINAL/drools-expert/html/ch04.html|here]]. We would recommend keeping things simple, and therefore provide an example below.
{{{
package com.thalesresearch.sensei.aaa
 
import com.thalesresearch.sensei.aaa.service.authorisation.decisionmaker.policybased.AuthorisationPolicyEngine.AuthorisationRequest;

// the default is to grant. so rules only need to specify the deny conditions

rule "Only USER can access https://sensei-dev1.grid.pub.ro:8443/rep-sensors"
	@url ("https://sensei-dev1.grid.pub.ro:8443/rep-sensors")
	@allowed ("USER")
	@denied ("All except USER")
	@comment ("Role based rule for sensor resources")
	when
		a : AuthorisationRequest( url == "https://sensei-dev1.grid.pub.ro:8443/rep-sensors" && role != "USER" )
	then
		System.out.println( a.getRole() + " not allowed to access https://sensei-dev1.grid.pub.ro:8443/rep-sensors" ); 
		a.setIsGranted(false);
end

rule "Only ADMIN can access https://sensei-dev1.grid.pub.ro:8443/rep-accounting"
	@url ("https://sensei-dev1.grid.pub.ro:8443/rep-accounting")
	@allowed ("ADMIN")
	@denied ("All except ADMIN")
	@comment ("Role based rule for accounting resources")
	when
		a : AuthorisationRequest( url == "https://sensei-dev1.grid.pub.ro:8443/rep-accounting" && role != "ADMIN" )
	then
		System.out.println( a.getRole() + " not allowed to access https://sensei-dev1.grid.pub.ro:8443/rep-accounting" ); 
		a.setIsGranted(false);
end
}}}
This shows 2 rules, which will be evaluated sequentially top to bottom. Each rule follows the pattern:
* rule "name", which can be anything
* @field ("content"), these are rule metadata used for logging.
* when<CR>a: !AuthorisationRequest(condition) : the condition to be evaluated, which in these cases is the REP URL being access controlled and the role of the requester
* then: whether access should be granted or not.

The roles which are evaluated in these rules are the roles contained in the tokens issued by the [wiki:Aaa STS].
=== Registering policies ===
The policies must be registered with the selected AAA service (defined in the aaaservice.uri property above). To do this, the policy files must be placed by the AAA service provider in the aaa.war/WEB-INF/classes/authorisation-policies folder.