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

== Identity provider: STS ==
A Security Token Service needs to be deployed for each security domain. 
=== Deployment ===
The STS is provided as a web app, to be deployed in a servlet container. A number of configuration options need to be set before rebuilding to package into a deployable WAR file.
==== Configure ====
The configuration files are located in src/main/webapp/WEB-INF. The Spring Security and authentication filters are configured in applicationContext-security.xml. The rest of the code is configured in applicationContext.xml.
However, many of the properties set in the Spring context can configured in the properties files located in src/main/resources. 
===== Keystore =====
The STS requires a JKS keystore that contains a private key. This is the key that will be used to sign all SAML objects such as assertions. A keystore can be generated using the Java Keytool. Instructions here: http://wiki.eclipse.org/Generating_a_Private_Key_and_a_Keystore 
The keystoreManager bean needs to be configured to use this keystore. This can be done by changing the following properties in metadata.properties:
||=Property=||=Description=||
||keystore.file||Location of the keystore. Default is security/keystore.jks||
||keystore.pass||Keystore password||
||key.alias||Certificate alias to be used for signing objects||
||key.pass||Password for the certificate alias||
Note that if you change the location of the keystore, you will also need to update the project’s POM so that the keystore is not filtered, as this will corrupt it. 
===== Hosted STS Metadata =====
The exchange of SAML metadata is the first stage in enabling SAML single sign-on. Entities that want to establish trust with the hosted STS will need to exchange metadata with the hosted STS. SAML metadata for the hosted STS can be generated by running the Junit test: 
{{{
com.thalesresearch.sensei.sts.service.trustedentity.saml.SamlMetadataGeneratorTestManual
}}}
By default, the generated metadata will be written to the following location:
{{{
src/main/resources/trustedEntities/hostedStsMetadata.xml
}}}
The metadata can be configured by changing the following properties in ‘metadata.properties’
||=Property=||=Description=||
||hostedSts.url||URL of the hosted STS. Used for the entity ID of the hosted STS.||
||hostedSts.wantIdpMetadataOnly||Boolean that sets whether the generated metadata also contains the metadata for the hosted Service Provider (needed for proxying authentication)||
||hostedSts.wantAuthnRequestsSigned||Boolean that sets whether the hosted STS requires Authentication Requests to be signed||
||hostedSts.ssoServiceRedirectUrl||String that sets the URL to which Service Providers should send Authentication Requests using the Redirect binding||
||hostedSts.tokenProcessing||String that sets the full URI to which STSs should POST assertions||
||hostedSp.signsAuthnRequests||Boolean that sets whether the hosted Service Provider signs authentication requests||
||hostedSp.wantAssertionsSigned||Boolean that sets whether the hosted Service Provider requires assertions to be signed||
||hostedSp.assertionConsumerUrl||String that sets the URL to which STSs should POST assertions||
===== Trusted Entity Register =====
The Trusted Entity Register contains the metadata for all trusted Service Providers and trusted STSs. It is configured in the metadataProvider bean in applicationContext.xml. 
To register a trusted entity, you will need the metadata for that entity either in a file or as a URL. Files containing metadata should be stored in src/main/resources/trustedEntities. Configure a bean for the entity using the org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider class for metadata contained in a file or the org.opensaml.saml2.metadata.provider.HTTPMetadataProvider class for metadata as a URL. 
In addition to holding the metadata for trusted entities, the Trusted Entity Register also contains the entity ID of the hosted STS. By default, the entity ID of the hosted STS is the same as the name used for creating the metadata for the hosted STS. 
===== Login properties =====
The following table lists properties in login.properties that can be used to customise the login process.
||=Property=||=Description=||
||loginForm.url||Sets the location of the login form. The default is senseiLogin.jsp, which is located in src/main/webapp||
||authFilter.url||Sets the URL that the login page should POST authentication requests to||
||success.url||Default page that successfully authenticated users will be sent to.||
||failure.url||Default page that users will be sent to if authentication fails||
The default login page, senseiLogin.jsp, can be easily customised. All of the labels are set in the messages.properties file in src/main/resources. The images used are located in src/main/webapp/images and can be replaced to customise the images displayed on the login page. 
==== Build ====
Once the STS has been configured, the application can be built using Maven by typing “mvn package”.
All dependencies are located in the following repositories:
* http://shibboleth.internet2.edu/downloads/maven2/
* http://repo1.maven.org/maven2/ 
The WAR file can then be deployed in a Java application server or container, such as Apache Tomcat. 
The STS is now ready. You can test login at /REST/SSO/login. 
=== User administration ===
The User Register contains user account data relating to users and their roles. It is configured in applicationContext-security.xml. 
The default configuration is an in-memory list that is populated using a properties file, “users.properties”. To add a user add the following to the file:
{{{
username=password,role[,role][,enabled|disabled]
e.g.	user1=password,USER,ADMIN,enabled
}}}
The implementation of the user register can easily be changed, for example, to a database by changing the configuration of the userRegister bean.  
The allowed roles are:
* GUEST
* USER
* OPERATOR
* ADMIN
* SECURITY_CONTROLLER

== Access control decision making: AAA block ==
A system provider MAY choose to deploy a AAA block. If it does not, resource and framework component providers wishing to use access control will have to provide their own.
=== Deployment ===
The AAA Service is provided as a web app, to be deployed in a servlet container. A number of configuration options need to be set in the WAR file before it is deployed.
==== Configure ====
The configuration files are located in /WEB-INF within the WAR file. The Spring Security and authentication filters are configured in applicationContext-security.xml. The rest of the code is configured in applicationContext.xml. However, many of the properties set in the Spring context can configured in the properties files located in /WEB-INF/classes. 
===== Keystore =====
The AAA Service requires a JKS keystore that contains a private key. This is the key that will be used to sign all SAML objects such as requests. A keystore can be generated using the Java Keytool. Instructions here: http://wiki.eclipse.org/Generating_a_Private_Key_and_a_Keystore 
The keystoreManager bean needs to be configured to use this keystore. This can be done by changing the following properties in metadata.properties:
||=Property=||=Description=||
||keystore.file||Location of the keystore. Default is classpath:keystore.jks||
||keystore.pass||Keystore password||
||key.alias||Certificate alias to be used for signing objects||
||key.pass||Password for the certificate alias||
===== Metadata =====
The exchange of SAML metadata is the first stage in enabling SAML single sign-on. Entities that wish to establish trust with the hosted AAA Service will need to exchange metadata. Therefore the STS used by the AAA Service to generate tokens must have the metadata for the AAA Service. Similarly, the AAA Service must have the metadata for the STS. The metadata follows the SAML 2.0 Metadata specification [1]. Metadata for the AAA Service should be created by hand or in the same way as for the STS above.
In addition, the following properties must be set in metadata.properties
||=Property=||=Description=||
||sts.uri||Location of the STS to use to generate tokens||
||sts.request.uri||URI on the STS to which requests for tokens should be sent||
||aaaservice.uri||Location of the hosted AAA Service||
===== Trusted Entity Register =====
The Trusted Entity Register contains the metadata for all trusted Service Providers and trusted STSs. It is configured in the metadataProvider bean in applicationContext-saml.xml. 
To register a trusted entity, you will need the metadata for that entity either in a file or as a URL. The default metadata files are stored in /WEB-INF/classes/trustedEntities. Configure a bean for each trusted entity using the org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider class for metadata contained in a file or the org.opensaml.saml2.metadata.provider.HTTPMetadataProvider class for metadata as a URL.  
===== Accounting =====
The database used for storing the accounting data may be configured by changing the following properties in application.properties. 
||=Property=||=Description=||
||jdbc.driverClassName||The fully qualified Java classname of the JDBC driver to be used||
||jdbc.url||The connection URL to be passed to the JDBC driver to establish a connection||
||jdbc.username||The connection username to be passed to the JDBC driver to establish a connection||
||jdbc.password||The connection password to be passed to the JDBC driver to establish a connection||
||hibernate.dialect||The classname of a org.hibernate.dialect.Dialect which allows Hibernate to generate SQL optimised for a particular relational database||
The AAA Service requires the following permissions for the database:
* Create
* Update
* Delete
* Select
* Insert
=== Management ===
==== Handling access controlled entities ====
* registering policies
tbd
* what policies should contain
tbd
==== Accounting interface ====
* what it does
The AAA Service records data about each request for an access control decision. It stores the following information:
* The time at which the request was received
* The username and role of the user accessing the resource
* The identifier of the requested resource
* The AAA decision and reason
The Accounting interface provides access to the accounting information stored by the AAA Service. 
* how to view / reset / etc
The Accounting data can be viewed at <aaaservice URI>/REST/Accounting
The data can also be cleared at <aaaservice URI>/REST/Accounting/ClearAll
Access to both of these URLs can be restricted by configuring the Spring Security Filter in applicationContext-security.xml