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

Table of Contents

1. AAA overview
2. Identity provider: STS
   1. Deployment
   2. User administration
3. Access control decision making: AAA block
   1. Deployment
   2. Management

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 ​here.

• Keystore

The STS requires a JKS keystore that contains a private key. A keystore can be generated using the Java Keytool. Instructions ​here.

• STS WAR file

The STS WAR file can be downloaded from here: 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 ​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 ​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 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 ​here.

• Keystore

The AAA service requires a JKS keystore that contains a private key. A keystore can be generated using the Java Keytool. Instructions ​here.

• AAA service WAR file

The AAA service WAR file can be downloaded from here: 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 ​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 ​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 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 <sts.uri>/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 here for more information on policies.

Accounting interface

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. For more information contact TRT (UK).