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 3 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/META-INF/maven/com.thalesresearch.sensei/sensei-sts-service/pom.xml

Configuration fields:

Field	Expected content
hosted.sts.url	URL of STS. This will be the Tomcat server URL route suffixed with /STS
keystore.filepath	File path of keystore, as an absolute path
keystore.password	Keystore password, defined during the keystore deployement
key.alias	Key alias, obtained from ???
key.password	Key password, obtained from ???
partner.aaaservice.filepath	File path of AAA Service metadata. how do you include multiple AAA services ??? This metadata is generated by ???
partner.sts1.filepath	File path of trusted STS metadata. This metadata is generated by ???
partner.sts2.filepath	File path of trusted STS metadata. This metadata is generated by ???

Note that more partner STS can be added, with incremental numbers. This allows peering between STS, and can be removed for a stand alone STS.

• sts.war/WEB-INF/classes/trustedEntities/hostedStsMetadata.xml

Configuration fields:

Field	Expected content
entityID	add the URL of this STS after the
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: COPY THESE FROM ABOVE

Field	Expected content
keystore.file	File path of keystore
keystore.pass	Keystore password
key.pass	Key password
key.alias	Key alias
partner.aaaservice.file	File path of AAA Service metadata
partner.sts1.file	File path of trusted STS metadata
partner.sts2.file	File path of trusted STS metadata

---

---

Configure

located in ???/WEB-INF.

Setting up a keystore

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

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