== 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)]]

== How-to: adding access control to my REP ==
=== 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.
==== Defining an access policy ====
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 the policy ====
There may be multiple AAA services running in the domain, and the resource provider must choose which to use (in a real life deployment they may differ in terms of SLAs, or service cost etc).
The AAA service implementation is provided as a WAR file deployed in a servelet container (see [wiki:Aaa|here]), and the policy files should be placed in the "/WEB-INF/classes/authorisation-policies" folder of the WAR file, and the AAA service restarted.
Adding, modifying or removing policies is done by changing the content of the "WEB-INF/classes/authorisation-policies" folder.
==== Configuring the Access Controlled REP ====
The access controlled REP is provided as a WAR file, to be deployed in a servelet container such as Apache Tomcat. The REP must be configured in the messages.properties file located in /WEB-INF/classes directory of the WAR file.
||= Property =||= Description =||
||rep.id||The identifier of the REP, which should be the URI||
||aaaservice.uri||The URI of the AAA Service||
||aaaservice.request.uri||The URI of the Request interface of the AAA Service||
||resDir.uri||The URI of the resource directory||