= System 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 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. TRT has deployed an STS on the PETP which can be used by the platform users. Others can be deployed as required. === 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 by editing property files in the WAR file before deployment. ==== Getting the software components for the STS ==== * 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]. * Keystore The STS requires a JKS keystore that contains a private key. A keystore can be generated using the Java Keytool. Instructions [http://wiki.eclipse.org/Generating_a_Private_Key_and_a_Keystore 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). ==== STS Configuration ==== The WAR file contains two files 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 STS. For more information contact TRT. 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 files: * sts.war/WEB-INF/classes/trustedEntities/hostedStsMetadata.xml Configuration fields: ||= '''Field''' =||= '''Expected content''' =|| ||entityID=||add the URL of this STS after this =|| ||ds:X509Certificate||encoded signing key of this STS (instructions on obtaining it [wiki:encoded_signing_key here]). Note this field appears twice in the file|| ||Location=||add the URL of this STS between the = and the /. Note this field appears twice in the file|| * sts.war/WEB-INF/classes/metadata.properties Configuration fields: ||= '''Field''' =||= '''Expected content''' =|| ||hostedSts.url||URL of this STS|| ||keystore.file||File path of keystore, as an absolute path|| ||keystore.pass||Keystore password, defined during the keystore deployement|| ||key.pass||Key password, defined during the keystore deployement|| ||key.alias||Key alias, defined during the keystore deployement|| ||partner.aaaservice.file^*||File path of AAA Service metadata, as described in pom.xml above|| ||partner.sts1.file^*||File path of a trusted STS metadata, as described in pom.xml above|| ||partner.sts2.file^*||File path of another trusted STS metadata, as described in pom.xml above|| ^* For simplicity of configuration, the STS is by default set to have one AAA service which it trusts, and up to two federated STS (i.e. a federation of three in all). If more AAA services of STSs are required to be used in the deployment, further configuration changes are required which are beyond the scope of this cookbook. Please contact TRT (UK) directly for further instructions. === User administration === The STS holds user accounts. These are configured in sts.war/WEB-INF/classes/users.properties, and require entries of the following type: {{{ username=password,role[,role][,enabled|disabled] e.g. joe.blogs=zsd*7d],USER,ADMIN,enabled }}} Modifying the users.properties file required a restart of the STS to take effect. The default deployment uses the following role semantics: * GUEST * USER * OPERATOR * ADMIN * SECURITY_CONTROLLER Other role semantics can be used, but require additional configuration. Please contact TRT (UK) directly for further instructions. == 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 by editing property files in the WAR file before deployment. ==== Getting the software components for the AAA service ==== * 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]. * Keystore The AAA service requires a JKS keystore that contains a private key. A keystore can be generated using the Java Keytool. Instructions [http://wiki.eclipse.org/Generating_a_Private_Key_and_a_Keystore here]. * AAA service WAR file The AAA service 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). ==== AAA Service Configuration ==== The WAR file contains two files 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 files: * aaa.war/WEB-INF/classes/trustedEntities/AaaMetadata.xml Configuration fields: ||= '''Field''' =||= '''Expected content''' =|| ||entityID=||add the URL of this AAA service after this =|| ||ds:X509Certificate||encoded signing key of this AAA service (instructions on obtaining it [wiki:encoded_signing_key here]).|| ||Location=||add the URL of this AAA service between the = and the /.|| * aaa.war/WEB-INF/classes/metadata.properties ||= '''Field''' =||= '''Expected content''' =|| ||keystore.file||File path of keystore, as an absolute path|| ||keystore.pass||Keystore password, defined during the keystore deployement|| ||key.alias||Key alias, defined during the keystore deployement|| ||key.pass||Key password, defined during the keystore deployement|| ||sts.metadata.file||File path to the trusted STS metadata. This metadata file is available from the STS provider (file name hostedStsMetadata.xml found in sts.war/WEB-INF/classes/trustedEntities/)|| ||sts.uri||URL of trusted STS|| ||sts.request.uri||URL of the trusted STS's request interface. By default /REST/SSO/Redirect|| ||aaaservice.uri||URL of this AAA Service|| === Management === ==== Policy management ==== REP access policies must be uploaded to the AAA service. Policy files must be placed in aaa.war/WEB-INF/classes/authorisation-policies, and the AAA service restarted after modification. See [wiki:RepAaa here] for more information on policies. ==== Accounting interface ==== The Accounting data can be viewed at /REST/Accounting. The data can also be cleared at /REST/Accounting/ClearAll. Access to both of these URLs can be restricted by configuring the Spring Security Filter in applicationContext-security.xml. For more information contact TRT (UK).