Configuration and Installation¶
Installation Requirements¶
- RDBMS (tested on MySQL 5.5+)
- Java 1.8+
- MongodDB 3.4+ (optional, needed for Authorization Module)
- Apache Maven (3.0+)
AAC configuration properties are configured through the corresponding Maven profile settings. By default, local
profile is activated and the execution environment is configured in the src/main/resources/application-local.yml
file.
The example configuration for the local execution is defined in application-local.yml.example
.
DB Configuration¶
DB Configuration is performed via the JDBC driver configuration, e.g. for MySQL:
jdbc:
dialect: org.hibernate.dialect.MySQLDialect
driver: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost:3306/aac
user: ac
password: ac
The schema and the user with the privileges should have been already configured.
IMPORTANT! The default configuration already contains MySQL driver version 5.1.40. In case a newer version
of the DB is used, update the driver version in pom.xml
accordingly.
AAC Endpoint Configuration¶
The way the AAC is exposed is configured via the following properties:
server.host
(or similar Spring Boot settings). Defaults tolocalhost:8080
server.contextPath
. Defaults to/aac
application.url
. The reverse proxy endpoint for the AAC needed, e.g., for the authentication callback.
Security Configuration¶
The following security properties MUST be configured for the production environment:
admin.password
: the password for the AAC administrator user.admin.contexts
: default role contexts managed by the platform. Defaults toapimanager, authorization, components
admin.contextSpaces
: default role spaces associated to the admin. Defaults toapimanager/carbon.super
(used by WSO2 API Manager as a default tenant)security.rememberme.key
: the secret key used to sign the remember me cookie.
For the user registration and the corresponding communications (email verification, password reset, etc), the SMTP email server should be configured, e.g.:
mail:
username: info@example.com
password: somepassword
host: smtp.example.com
port: 465
protocol: smtps
Configuring Identity Providers¶
By default, AAC relies on the internally registered users. However, the integration with the external identity provider is supported. Out of the box, the support for the OAuth2.0 providers can be achieved through the configuration files. Specifically, to configure an OAuth2.0 identity provider it is necessary to specify the OAuth2.0 client configuration in the properties, e.g. for Facebook,
oauth-providers:
providers:
- provider: facebook
client:
clientId: YOUR_FACEBOOK_CLIENT_ID
clientSecret: YOUR_FACEBOOK_CLIENT_SECRET
accessTokenUri: https://graph.facebook.com/oauth/access_token
userAuthorizationUri: https://www.facebook.com/dialog/oauth
preEstablishedRedirectUri: ${application.url}/auth/facebook-oauth/callback
useCurrentUri: false
tokenName: oauth_token
authenticationScheme: query
clientAuthenticationScheme: form
scope:
- openid
- email
- profile
Besides, it is necessary to describe the provider and the possible identity mappings in
src/main/resources/it/smartcommunitylab/aac/manager/authorities.xml
file. The configuration amounts to
defining the properties to extract, mapping name and surname properties, defining the unique identity attribute
for the provider, and relations to the other providers’ attributes (e.g., via email). For example,
<authorityMapping name="google" url="google" public="true" useParams="true">
<attributes alias="it.smartcommunitylab.aac.givenname">given_name</attributes>
<attributes alias="it.smartcommunitylab.aac.surname">family_name</attributes>
<attributes alias="it.smartcommunitylab.aac.username">email</attributes>
<attributes>name</attributes>
<attributes>link</attributes>
<identifyingAttributes>email</identifyingAttributes>
</authorityMapping>
defines the Google authentication attributes. Specifically, the email
attribute is used to uniquely identify
Google users.
Authorization Module¶
AAC allows for integration of the authorization module, where it is possible to configure the access rights for
the user at the level of data. To enable the authorization module, the corresponding authorization
Maven profile
should be activated.
Logging Configuration¶
The logging settings may be configured via standard Spring Boot properties, e.g., for the log level
- logging:
- level:
- ROOT: INFO
The project relies on the Logback configuration (see src/main/resources/logback.xml
). The default
configuration requires the log folder path defined with aac.log.folder
property. (if the property is not set, application will use default value: WORKING_DIRECTORY/logs).
OpenID Configuration¶
AAC provide a basic implementation of the OpenID protocol. The implementation is based on the MitreID project.
To configure the issuer, it is necessary to specify the OpenID issuer URL:
openid:
issuer: http://localhost:8080/aac
OpenID extension requires RSA keys for JWT signature. The project ships with the pre-packaged generated key. The key MUST be replaced with your specific value in production environment. To generate new key please follow the instructions available here.
The resulting key should be placed in the resources (i.e., src/main/resources).
The OpenId metadata is available at /.well-known/openid-configuration
.
Execution¶
To execute from command line, use maven Spring Boot task:
mvn -Plocal spring-boot:run
In case you run the tool from the IDE, add the profile configuration to the VM parameters:
-Dspring.profiles.active=local
To enable the authorization module, add the corresponding profile to the profile list (comma-separated)
Once started, the AAC tool UI is available at http://localhost:8080/aac
.