d6.2: aaa provisioning services and mechanisms · 2018-04-10 · gui screenshots, onfiguration...

1

www.eubra-bigsea.eu | [email protected] |@bigsea_p3peubr

D6.2: AAA provisioning services and mechanisms

Author(s)

Paulo Silva (UC), Paulo Simões (UC), Edmundo Monteiro (UC), Rui Queiroz (UC), Tânia Basso (UNICAMP), Eduardo Morais (UNICAMP), Roberta Matsunaga (UNICAMP), Nuno Antunes (UC), Regina Moraes (UNICAMP), Rogerio de Lemos (UC), Marco Vieira (UC)

Status Draft/Review/Approval/Final

Version V1.0

Date 05/10/2017

Dissemination Level

X PU: Public

PP: Restricted to other programme participants (including the Commission)

RE: Restricted to a group specified by the consortium (including the Commission)

CO: Confidential, only for members of the consortium (including the Commission)

Abstract:

Europe - Brazil Collaboration of BIG Data Scientific Research through Cloud-Centric Applications (EUBra-

BIGSEA) is a medium-scale research project funded by the European Commission under the Cooperation

Programme, and the Ministry of Science and Technology (MCT) of Brazil, in the frame of the third European-

Brazilian coordinated call.

This document describes the implemented AAA provisioning services and mechanisms in the scope of the

EUBra-BIGSEA project, organized in two sets: the services provided to the applications (AAAaaS) and the

AAA services for accessing the infrastructure resources (iAA). Along with the description of key

functionalities, usage examples are presented and deployment issues are discussed.

EUBra-BIGSEA is funded by the European Commission under the

Cooperation Programme, Horizon 2020 grant agreement No 690116.

Este projeto é resultante da 3a Chamada Coordenada BR-UE em Tecnologias da Informação

e Comunicação (TIC), anunciada pelo Ministério de Ciência, Tecnologia e Inovação (MCTI)

2


TABLE OF CONTENTS

1. Introduction ................................................................................................................................................ 7

1.1. Target Audience ................................................................................................................................ 8

1.2. Scope of the document ..................................................................................................................... 8

1.3. Structure of the Document ............................................................................................................... 9

2. AAA Products ............................................................................................................................................ 10

2.1. Applications AAAaaS ....................................................................................................................... 10

2.1.1. AAAaaS Graphical User Interface (GUI) ...................................................................................... 11

2.1.2. AAAaaS REST API Endpoints ....................................................................................................... 12

2.2. Infrastructure Authentication and Authorisation - iAA .................................................................. 14

2.3. Summary ......................................................................................................................................... 16

3. Interaction with AAA as a Service API ...................................................................................................... 17

3.1 AAAaaS API for Authentication ....................................................................................................... 17

3.1.1 REST API endpoints ..................................................................................................................... 17

3.1.2 Authentication ............................................................................................................................ 18

3.1.3 Token verification ....................................................................................................................... 19

3.1.4 Read user information ................................................................................................................ 19

3.1.5 Sign up ........................................................................................................................................ 19

3.1.6 Sign out ....................................................................................................................................... 20

3.1.7 Update user information ............................................................................................................ 20

3.1.8 Delete user account .................................................................................................................... 21

3.1.9 Change password ........................................................................................................................ 21

3.1.10 Forgot password ..................................................................................................................... 21

3.2 AAAaaS API for Authorisation ......................................................................................................... 22


3.2.2 Create authorisation rule ........................................................................................................... 23

3.2.3 Update authorisation rule .......................................................................................................... 23

3.2.4 Show authorisation rule ............................................................................................................. 23

3.2.5 Delete authorisation rule ........................................................................................................... 24

3.2.6 Use resource ............................................................................................................................... 24

3.3 AAAaaS API for Accounting ............................................................................................................. 25


3


3.3.2 Read accounting ......................................................................................................................... 25

3.4 Create Email Association ................................................................................................................. 26

3.4.1 Read Email Association ............................................................................................................... 26

3.4.2 Delete Email Association ............................................................................................................ 26

3.5 Favorites REST API endpoints .......................................................................................................... 27

3.5.1 Create Favorite ........................................................................................................................... 27

3.5.2 Read Favorite .............................................................................................................................. 28

3.5.3 Read all favorites from a user ..................................................................................................... 28

3.5.4 Delete Favorite............................................................................................................................ 29

3.6 Redirection Addresses and page layouts ........................................................................................ 29

3.6.1 Login Page ................................................................................................................................... 29

3.6.2 Sign Up Page ............................................................................................................................... 30

3.7 Update user details ......................................................................................................................... 34

3.7.1 Update account details ............................................................................................................... 34

3.7.2 Add Secondary email .................................................................................................................. 35

3.7.3 Change password ........................................................................................................................ 36

3.7.4 Delete user account .................................................................................................................... 37

3.7.5 Reset Password ........................................................................................................................... 37

3.7.6. Resend Confirmation Email ........................................................................................................ 38

3.8 Configuration for redirects (popup’s) ............................................................................................. 39

3.8.1 Button to create popup with “Sign In” page .............................................................................. 40

3.8.2 Button to create popup with “Sign Up” page ............................................................................. 41

3.9 External Login with Google ............................................................................................................. 42

3.10 Initialization of services .................................................................................................................. 43

3.10.1 Dockerfile (single components).............................................................................................. 43

3.10.2 Docker-compose (sequentially) .............................................................................................. 44

3.10.3 Marathon................................................................................................................................ 44

3.11. Summary ......................................................................................................................................... 48

4. Interaction with the iAA API ..................................................................................................................... 48

4.1. REST API Endpoints ......................................................................................................................... 48

4.2. Infrastructure Authentication ......................................................................................................... 48

4.3. Insert data for infrastructure authentication (for administrators use) ........................................... 49

4.4. Summary ......................................................................................................................................... 49

5. Integration of Services .............................................................................................................................. 50

5.1. Melhor Busão .................................................................................................................................. 50

4


5.2. Routes for People ............................................................................................................................ 50

5.3. Broker .............................................................................................................................................. 50

5.4. UPV Cluster ..................................................................................................................................... 51

5.5. Summary ......................................................................................................................................... 53

6. Final Considerations and Next Steps ........................................................................................................ 54

References ........................................................................................................................................................ 55

5


Document identifier: EUBRA BIGSEA -WP6-D6.2

Deliverable lead UC

Related work package WP6

Author(s) Paulo Silva (UC), Rui Queiroz (UC), Paulo Simões (UC), Edmundo Monteiro (UC), Rui Queiroz (UC), Tânia Basso (UNICAMP), Eduardo Morais (UNICAMP), Roberta Matsunaga (UNICAMP), Nuno Antunes (UC), Regina Moraes (UNICAMP), Rogerio de Lemos (UC), Marco Vieira (UC)

Contributors

Due date 31/08/2017

Actual submission date 05/10/2017

Reviewed by Ignacio Blanquer (UPV)

Approved by

Start date of Project 01/01/2016

Duration 24 months

Keywords AAA services, security strategy

Version Date Authors Notes

0.1 23/06/2017 Regina Moraes (UNICAMP), Eduardo Morais

Initial Structure and Technical models

0.2 26/06/2017 Paulo Silva (UC) Sequence Diagrams, Architecture, API examples,

GUI screenshots, Configuration instructions

0.3 31/07/2017 Paulo Silva (UC), Regina Moraes

(UNICAMP), others

Second round of integrated contributions

0.4 20/08/2017 Paulo Silva (UC), Regina Moraes

(UNICAMP), others

Third round of integrated contributions

0.5 20/09/2017 Paulo Silva (UC), others Revised version for internal review

1.0 05/10/2017 Paulo Silva (UC), others Final version after internal review

6


Copyright notice: This work is licensed under the Creative Commons CC-BY 4.0 license. To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0.

Disclaimer: The content of the document herein is the sole responsibility of the publishers and it does not necessarily represent the views expressed by the European Commission or its services.

While the information contained in the document is believed to be accurate, the author(s) or any other participant in the EUBra-BIGSEA Consortium make no warranty of any kind with regard to this material including, but not limited to the implied warranties of merchantability and fitness for a particular purpose.

Neither the EUBra-BIGSEA Consortium nor any of its members, their officers, employees or agents shall be responsible or liable in negligence or otherwise howsoever in respect of any inaccuracy or omission herein.

Without derogating from the generality of the foregoing neither the EUBra-BIGSEA Consortium nor any of its members, their officers, employees or agents shall be liable for any direct or indirect or consequential loss or damage caused by or arising from any information advice or inaccuracy or omission herein.

EXECUTIVE SUMMARY

The EUBra-BIGSEA project aims at developing cloud services empowering Big Data analytics to ease

the development of massive data processing applications. For this, the project requires the

research of efficient mechanisms to ensure privacy and security, on top of a QoS-aware layer for

the smart and rapid provisioning of resources in a cloud-based environment.

The security concerns of a large and complex system should not be addressed individually or in an

ad-hoc manner, as this may result in inadequate solutions. This is even more important in the

context of complex systems such as the one being developed in the context of the EUBra-BIGSEA.

So, a coordinated strategy allowing to achieve the appropriate level of security is mandatory. Such

strategy, already discussed in the previous Deliverable D6.1, guides the research, development

and integration of the security solutions along the project.

One of the pillars of this strategy corresponds to the inclusion of AAA (Authentication,

Authorisation and Accounting) solutions into the EUBra-BIGSEA platform, including two distinct

AAA blocks: 1) the EUBra-BIGSEA iAA Service, to provide infrastructure-level AA (Authentication

and Authorization) functionalities to infrastructure managers and application

developers/providers; and 2) the EUBra-BIGSEA Applications AAAaaS (Authentication,

Authorization and Accounting as a Service), focused on the authentication and authorization of

the end users of applications hosted in the EUBra-BIGSEA platform.

This document presents the two forementioned AAA blocks, which have been developed and

integrated in the scope of EUBra-BIGSEA framework and, combined together, provide the AAA

services required for operating the EUBra-BIGSEA applications and underlying infrastructure. As

discussed along the document, these two blocks share several architectural similarities, despite

serving distinct purposes. They were both implemented according to a common modular design

which allows both sharing several common components (in order to reduce software development

and maintenance costs) and adequate cloud-based deployment and lifecycle management

strategies.

7


1. INTRODUCTION

Large and complex systems as the those envisioned by the EUBra-BIGSEA project need a coordinated solution

to guarantee adequate levels of security. A common example of an ineffective ad-hoc manner to tackle the

security features is that adding encryption to a system does not make it secure, as it is enough that the

software has some vulnerabilities to expose the system to attackers. The reverse is also true, as a correctly

implemented software cannot guarantee the security of the system if the infrastructure is incorrectly

configured.

An important security requirement is the correct identification of users. Since cloud services are accessed

remotely, it is crucial to have means to univocally authenticate users. Cryptography can be used to solve this

problem, for example by the utilization of digital certificates, and to protect passwords on databases. After

user authentication, the system still must maintain control over what he or she can or cannot do. In other

words, we must provide authorisation mechanisms, such that the system is able to verify which services are

allowed or not for a determined user. The main objective of this work is to implement AAA (authentication,

authorisation, accounting). The first and second A’s are more commonly used, but the last one, accounting,

is usually ignored during the design of security solutions. However, it is also a relevant requirement, since it

is responsible for collecting information that allows further investigations in the case of attacks, but also

because it provides precise knowledge about resources utilization.

This is particularly challenging in the context EUBra-BIGSEA project. Thus, it was of the utmost importance to

define a coordinated strategy with the other technical work packages. Such strategy, defined in terms of the

requirements to be met, was defined in D6.1 and it is being used to guide the research, development and

integration of the security solutions along the project.

In this deliverable, the provisioning services and mechanisms of Authentication, Authorisation and

Accounting (AAA) are presented. Due to the criticity of the data stored, managed, and analyzed, AAA

services/mechanisms have to be provided to support the data scientists that use the framework. In addition,

the link between the external services/users and the Application Development Services is the most critical

aspect, as it provides the external access point to the platform. These services are transversal to all the

components.

Although conventional AAA solutions are available, like for example Radius, Diameter and TACACS+, not many

complete solutions are constructed in the context of cloud computing. Nevertheless, it is possible to point

out many tools that can be used to offer specific features. In particular, there are a plethora of Authentication

mechanisms not only proposed in the literature, but also extensively implemented in different programming

languages and platforms. One such solution is OpenID, which offers identification mechanisms and its broad

usage makes it an interesting option. Another technology that has been used is the SSO (Single Sign-On),

which allows to delegate the authentication functionality to an external SSO service like the ones offered by

Google and Facebook.

Nowadays, we have seen a growth in the use of multifactor authentication. In this work [2] authentication

techniques that could be implemented in order to improve security are discussed. Considering its simplicity,

we have OTP (one-time passwords) [3], which offer a good alternative to easily deploy a two-factor

authentication mechanism and therefore seems to be the best cost-benefit.

8


Considering the specific demands of the EUBra-BIGSEA project, it was decided to initiate the implementation

using simple solutions for each module. For example, Authentication is implemented by using password-

based mechanisms. This allows us to establish the API architecture and to determine the best service

interface. Thus, the first question raised was whether password-based authentication is sufficient. Many

researchers claim for substituting passwords by cryptographic methods, like for example certificate-based

solutions. However, deploying such systems is not a simple task, requiring higher costs and leading to less

usable software, as pointed out for instance by [1], which after comparing several authentication solutions

conclude that password-based authentication is still the main choice in practice.

In order to manage Authorisations and Accounting, a simple API was proposed and implemented. The API

allows integration with technologies such as OAuth (through Google API’s).

1.1. Target Audience

This document is mainly intended for internal use, although it is publicly released. At internal level, WP6

members will use the document as a report for performed work and guide for future usage and further

developments. Researchers from the remaining WPs will be able to know what has been developed in terms

of AAA solutions and how these services can be used by EUBra-BIGSEA applications.

The document thus refines the security scope and concerns of the EUBra-BIGSEA infrastructure, taking into

account the concerns of the remaining work packages, reviews the state of the art regarding solutions in the

scope of the work package and related to the concerns identified, presents the concrete security

requirements implemented so far, which will cover those concerns, and stands out the ones implemented by

using/adapting existing solutions and the ones for which new solutions are provided (gaps).

1.2. Scope of the document

This document describes the AAA provisioning services and mechanisms developed in the scope of the EUBra-

BIGSEA framework. Task D.6.2 proposed specific requirements for the AAA provisioning. The work reported

in this delivery is the result of pursuing such requirements. Therefore, before proceeding to the presentation

of the developed work, a listing of the proposed requirements follows:

Applications AAAaaS:

- Support for B2C (Business to Consumer Identity and Access Management (IAM) functionalities (must-

have));

- Support for external identity providers (must-have);

- Support for High Availability with Dynamic Elasticity (nice to have);

- Support for Application-level Accounting Mechanisms (nice to have).

9


Infrastructure AAA (designated iAA in the document):

- Provide a Cloud Manager Framework-Agnostic solution (must have);

- Support Identity Access and Access Control Management functionalities (must-have);

- Support for base Cloud Manager Framework adopted by EUBra-BIGSEA (must-have);

- Provide a common Authentication to the Infrastructure (must-have);

- Support for authentication using external Identity Providers and support for Federation (nice to

have);

- Support for Accounting Data across underlying frameworks (nice to have).

This document refers to AAAaaS Applications and Infrastructure AAA (iAA). The following chapters describe

each module, its characteristics as well as examples for each case. Also, in every case it is explained the

relationship with each requirement and its completion.

1.3. Structure of the Document

The rest of this document is structured in four main sections, as follows. Section 2 defines the project AAA

solutions. Section 3 presents a solution to be used by developers to provide their applications with an AAA

service. Section 4 presents the infrastructure Authentication and Authorisation (iAA). It is a complementing

solution to AAAaaS, fulfilling the needs of authentication and authorisation for Infrastructure users. Section

5 describes the integration of the AAA services in different scenarios. Section 6 presents the final

considerations and discusses the next steps of this work.

10


2. AAA PRODUCTS

The two main blocks generated from this work are the Applications AAAaaS and the iAA. While sharing several similarities and common components, they address different target functionality. The first is focused on applications and interaction with end-users. The second is more focused on the access to the infrastructure.

The solutions were implemented using Python and tools like MongoDB and CFSSL, to generate and manage certificates, Docker and Docker-compose, to separate each component in a way that makes the solutions easy to deploy on cloud systems and more scalable. Each component is built on a Docker container. Since we are able to control each part separately, it is possible to find bottlenecks and tune our system to respond appropriately. The web server is Nginx, and the REST API is implemented using Pyramid. Nginx can do load balancing by instantiating new Pyramid instances on-demand. Each component was tested using unit tests and a shell script was developed to test the whole system, basically executing cURL commands to validate the REST API implementation.

Next, we present an introduction of these two blocks.

2.1. Applications AAAaaS

Figure 1 shows the architecture of the Applications AAAaaS solution implemented in EUBra-BIGSEA. Users access the applications that interact with the cloud environment. The Docker containers are orthogonal to the solutions. The webpages (front-end layer) can be used or not by the applications.

In the Applications AAAaaS module there are two main interaction interfaces: the AAA server Graphical User Interface (GUI) and, through each application, the AAA server API endpoints integrated in the application. These two points are presented in detail in Section 4 (Interaction with AAA as a Service API). Next, we present a brief introduction to these two points.

11


Figure 1: Applications AAAaaS Architecture

2.1.1. AAAaaS Graphical User Interface (GUI)

The AAA server interface exposes web pages with forms for a user to introduce its login credentials, to register, update, change or add user information, to delete account, reset or change password and resend confirmation email. The AAA server user interface provides access to all the functionality of the AAA.

In this option, considering the login action as an example, when the user presses the login button in the application, it is forwarded to the AAA authentication server, which shows up a login page where he or she can introduce its credentials.

The sequence diagram presented in Figure 2 details the login flow for a user’s login using the AAA server authentication page. There are two possibilities: local authentication (AAA Server is responsible for the authentication), external authentication (for example, Google authentication).

12


Figure 2: AAA server authentication user sign in

2.1.2. AAAaaS REST API Endpoints

By using the application’s user interface, the user interactions with authentication related options (e.g. login, register) are made within the application. Upon those interactions, the application makes requests to the AAA authentication server (REST API). The requests contain the user related information for validation (e.g. username, password) or registration.

In this option, considering the login action as an example, when the user presses the login button in the application, he/she is presented with a login page within the application where he/she can introduce the credentials. Then, the application makes a request to the AAA authentication server API in order to validate the user’s credentials. After the validation of the request, if it is positive, the AAA authentication server replies back to the application with a token associated to the user credentials that were being verified - confirming that the user exists and was successful authentication.

The sequence diagram presented in Figure 3 shows the login flow for a user’s login using the application user interface. The application makes a request with the user’s credentials for validation. If the credentials are

13


validated, the application receives a token that was generated by the system, otherwise the application receives an error message and the process ends.

Figure 3: Application user interface sign in

The details of the signup process are presented in Figure 4. When the user presses the sign up button, the application requests the AAA Server to send the sign up page. Then, user insert her/his information in the form and submits it. The server validates the user information and returns a message if there are incorrect fields, or if the username submitted has already been stored in the database. Otherwise, the AAA Server sends the information to the database and registers a new entry.

14


Figure 4: AAA server sign up webpage

2.2. Infrastructure Authentication and Authorisation - iAA

In addition to the Applications AAAaaS, there is the iAA (infrastructure Authentication and Authorisation). This module deals with authentication and authorisation of infrastructure accesses. It provides a graphical user interface as well as an API.

The iAA module provides an endpoint so Mesos agents or frameworks can authenticate themselves and gain clearance to access certain resources. The module is working as a middleware between Mesos agents or frameworks and the Mesos master. It can be easily adapted to support different frameworks executed from the CLI and it allows changes, e.g. updates, to be made to Mesos without having a disruptive effect on the iAA process

The users’ interactions with the iAA’s GUI interface include the “Sign Up” process, changing or updating information, changing or reseting password and accessing other authorization and accounting features. Although every feature is equally accessible through API endpoints, the authentication requested from the infrastructure itself is made directly to the API endpoint. This means that the infrastructure verifies directly with the iAA module if a user has the correct permissions to enter or run tasks on the infrastructure. The

15


verification is made automatically by calling specific API endpoints. Then, each request contains information on whether each user is authorized or not.

Figure 5 shows the architecture of the iAA solution implemented in EUBra-BIGSEA.

Figure 5: iAA Architecture Solutions

Users access the web pages to sign up and create an account. Then that account is used for the interaction with the infrastructure environment. The Docker containers are orthogonal to the solutions as well as the monitoring services. The webpages (front-end layer) can be used for signing up or to modify account information.

This iAA control is carried out in accordance with the data (credentials and ACLs) present on the Mesos master. To achieve this, a mapping between the credentials created by the user and a set of credentials previously loaded on the Mesos master is done. This means that each registered user is assigned with a pair of Mesos credentials (principal and secret). This action is completely transparent to the user.

Therefore, the process of authentication occurs as follows:

1. The user executes the usual CLI command to start the agent (or frameworks) but adds the authentication credentials as parameters, according to the register that has been made (among other Mesos parameters that users choose to use).

2. These credentials are then sent via a HTTPS request (post) to the authentication endpoint (described in section 4.2) which is predefined in a text file so it can be easily changed.

16


3. If this authentication step is successful, the reply message to the previous request will contain the Mesos credentials. Also, a message will be shown to the user confirming the successful or unsuccessful authentication process.

4. These credentials are then processed as to allow their use in the next step.

5. The authenticated connection to the Mesos master is then established. This connection considers the other parameters used by the user when executing the command to start the agent.

After the first step, the whole process takes place without the user intervention.

Usage example:

To authenticate, Mesos agents simply execute the following command through the CLI adding the username and password previously created. The order of the access credentials must be respected as presented in the following example and must be the first parameters to be included, other typical flags/arguments may follow:

./mesos_auth --u [username] --p [password] --[other flags and parameters]

eg. ./mesos_auth --u User1 --p Password1 --master=127.0.0.1:5050 --work_dir=/var/lib/mesos

2.3. Summary

This chapter introduces the two solutions developed for the AAA provisioning services and mechanisms. It presents the architecture of each one of the modules: AAA as a Service for Applications; and Infrastructure AAA (IAA). For each, their core functionalities and main characteristics are described. Functionalities like sign in or sign up are also described using flow diagrams. This chapter sets the base for the detailed description and exemplification of the specific endpoints developed for each module, described in the next chapter.

17


3. INTERACTION WITH AAA AS A SERVICE API

The backend component was designed to enable a straightforward adaptation of the AAA by applications in context of cloud computing. The use of Docker containers provides an isolation of the AAA from the rest of the system. Furthermore, the proposed REST API can be reused and new functionalities can be easily added and deployed.

3.1 AAAaaS API for Authentication

This subsection details the authentication service implemented in the AAAaaS API for the EUBra-BIGSEA project. Endpoints, examples and validations are given to help in the use of the solutions implemented.

3.1.1 REST API endpoints

Table 1 describes the REST calls that can be made to the AAA authentication server API. The first column of the table shows the calls' address and the second shortly describes the actions. The currently available methods allow the following: signing up of a new user; signing in of an existing user; verification of a token associated to a user; verification of token and retrieval of complete user information; signing out of a user; updating/changing user information; deleting user account; changing user password; retrieval of forgotten password.

Table 1: AAA Manager - Authentication REST API endpoints

Address Action

engine/api/checkin_data POST method, verifies credentials and provides user data

engine/api/verify_token POST method, verifies token and replies with username

engine/api/read_user_info POST method, verifies token and replies with detailed user information

engine/api/signup_data POST method, creates user entry in database

engine/api/checkout_data POST method, invalidates token from user

/engine/api/update_user POST method, updates user information

/engine/api/delete_user POST method, deletes user account

/engine/api/change_password POST method, changes the password

engine/api/forgot_password POST method, sends email with new password

https://eubrabigsea.dei.uc.pt/engine/api/checkin_data

https://eubrabigsea.dei.uc.pt/engine/api/verify_token



18


Next, we present examples with cURL commands of the described methods. The examples contain the method call (data and endpoint) as well as the respective responses in positive and negative case (if applicable).

In general, if some mandatory field is missing, the component returns the following:

{'error': 'Missing mandatory parameter: [NAME]'},

where [NAME] corresponds to the missing field name.

If the given token is invalid or if it doesn’t correspond to the given username, then it returns:

{'error': 'Invalid token'}

3.1.2 Authentication

First of all, in order to use resources the user must authenticate into the system. This process is carried out by service checkin_data, which is responsible for verifying the validity of the credentials provided, returning to the user a token that can be used to access other services later.

Next, we present a few examples of request and response in the positive and negative cases, when checkin_data is invoked. curl --data "user=testuser&pwd=aB123456" https://eubrabigsea.dei.uc.pt/engine/api/checkin_data Response in the positive case: {"error": "", "success": true, "cancelled": false, "user_info": {"user_token": "d95e965b4e818ab8150e1a25a4890fd31c2c662e1b8a7c86b6664a7bd3f4e336d763822e25acd762f27d787cbe8fdb55cdde655d72b4d76748541bb6d059decc", "user": {"lname": "silva", "username": "testuser", "fname": "paulo"}}} Response in the negative case: {"error": "Invalid username or password.", "success": false, "cancelled": false, "user_info": null} In addition, the request accepts an option where the user chooses to stay signed in for a longer period (7 days maximum - then he/she must sign in again). The option is to add stayin option selected as “true” or “false” as follows: curl --data "user=testuser&pwd=aB123456&stayin=true" https://eubrabigsea.dei.uc.pt/engine/api/checkin_data Response in the positive case: {"error": "", "success": true, "cancelled": false, "user_info": {"user_token": "d95e965b4e818ab8150e1a25a4890fd31c2c662e1b8a7c86b6664a7bd3f4e336d763822e25acd762f27d787cbe8fdb55cdde655d72b4d76748541bb6d059decc", "user": {"lname": "silva", "username": "testuser", "fname": "paulo", "stayin": true}}} Response in the negative case: {"error": "Invalid username or password.", "success": false, "cancelled": false, "user_info": null}

19


3.1.3 Token verification

After the validation of user’s credentials, the application receives a token that was generated by the system. To place a request, this token needs to be verified. The system verifies the token and the response in the positive and negative cases are as follows.

Request (with token gathered from previous example): curl --data "token=67c45c889b9172ca7e4f9ea4e1de256d1486af5b911bae50b367605e1dfc9bac319adb1654c31e43e8657d9b72825cc5e421764bf5e58e971dab2ee66e213902" https://eubrabigsea.dei.uc.pt/engine/api/verify_token Response in the positive case (the username associated with the token): {"response": "testuser"} Response in the negative case (if token does not match any user): {"response": "invalid token"}

3.1.4 Read user information

Once the user is authenticated and the token validated, the user can access to his/her information using the following request. Also, the responses in positive and negative cases are listed below. Request (with token gathered from previous example): curl --data "token=67c45c889b9172ca7e4f9ea4e1de256d1486af5b911bae50b367605e1dfc9bac319adb1654c31e43e8657d9b72825cc5e421764bf5e58e971dab2ee66e213902" https://eubrabigsea.dei.uc.pt/engine/api/read_user_info Response in the positive case (the username associated with the token): {"success": "User info read successfully.", "response": {"username": "testuser", "fname=testname&lname=testsurname&[email protected]"}} Response in the negative case (if token does not match any user): {"success": "User info read successfully.", "response": "invalid token"}

3.1.5 Sign up

To access data from the database, an entry should be added to the database using the following request. Request: curl --data "user=testuser&pwd=aB123456&fname=testname&lname=testsurname&[email protected]" https://eubrabigsea.dei.uc.pt/engine/api/signup_data

20


The username must be unique and the response as success or no success is sent as follows: Response in the positive case: {"success": "User signed up with success!"} Response in the negative case: {"error": "Username already exists. Please choose a different one."} After a successful sign up process, it is necessary to confirm the account. This is made through a confirmation sent to the email indicated by the user. In the email, there is a link that the user can click or copy and paste to the browser. Figure 6 shows the email that is sent to the user.

Figure 6: Account Confirmation Email

3.1.6 Sign out

The user can logout by using the service checkout_data, which is responsible for invalidating the user token provided.

Request (with token of the user signing out):

curl --data "token=84e1a2f2ef6ee78240ad98af4cf055837f167feac554cb5bc6e6c69a1b76227429be37fc05060a8c82852fd8aef03dc3769e1c244603cc82a5267b4f6282576a" https://eubrabigsea.dei.uc.pt/engine/api/checkout_data

Response (the response is always empty, whether the token exists or not): {}

3.1.7 Update user information

The user can update the profile information by using service update_user. Next an example of utilization of this method is presented.

curl --data "user=newuser&fname=testnamechange&lname=testsurname&[email protected]&token=JDJiJDEyJDRXYjhydWhub2JBLlpRNjNOUVhzQ080S3NRcDNYd1lvb2Z3Um9pUnBCL0UzejlnQ0hPa1p1" https://eubrabigsea.dei.uc.pt/engine/api/update_user

Response in the positive case: {"success": "User information updated successfully."}

https://eubrabigsea.dei.uc.pt/engine/api/update_user



21


Response in the negative case: {"error": "Username does not exist."}

3.1.8 Delete user account

In order to delete an account, service delete_user can be used as follows.

curl --data "user=test&token=JDJiJDEyJE95SXdlcjFJdm5jaGlqMU9uVnM1TWVRMlE2b2RnZ1Jaa1VsYy83L3psS3dvMTlwMDlKdHRL" https://eubrabigsea.dei.uc.pt/engine/api/delete_user

Response in the positive case: {"success": "User deleted with success."} Response in the negative case: {"error": "User does not exist."}

3.1.9 Change password

The user can change his or her password by calling method change_password. If the new password fulfils the security policy, then the database will be updated with the bcrypt hash function of the new password, which protects against dictionary attacks.

Request:

curl --data "user=testuser&oldpwd=@@@123456Hi&newpwd=@@@12345678Hello&token=JDJiJDEyJDNtVzQ0Nkk4V2xPZWR5eDc0S0w0Ri5xc3hpNkMua1pyc05IZ1paQlNXeEVWZEp6OEY0NGgu" https://eubrabigsea.dei.uc.pt/engine/api/change_password

Response in the positive case: {"success": "Password updated successfully."} Response in the negative case: {"error": "Username does not exist."}

3.1.10 Forgot password

The user can use method forgot_password to change his or her current password. The AAA Manager will generate a random and secure password and it will be sent by email to the user.

Request:

curl --data "username=testreg&[email protected]" https://eubrabigsea.dei.uc.pt/engine/api/forgot_password

https://eubrabigsea.dei.uc.pt/engine/api/delete_user



22


Response in the positive case: {"success": "Email sent with success."}

Response in the negative case: {"error": "Email was not sent."}

3.2 AAAaaS API for Authorisation

The authorisation component allows the creation of authorisation rules that control and authorize user’s access to resources. This component is structured as follows: resource name; resource type; max_used; used; application id; url; blob.

Currently, each user can add authorisation rules, edit and delete their own rules. The administrative role is being set up and will be available in the next update of the service. After this, only an administrator will be able to create, modify or delete user authorisation rules. A user will be limited to read-only access.


Table 2 describes the REST calls that can be made to the AAA authorisation server API. The first column of the table shows the calls' address and the second shortly describes the matching actions. The currently available methods allow to: create authorisation, update authorisation, read authorisation, read authorisations, delete authorisation and use resources.

Table 2: AAA Manager - Authorisation REST API endpoints

Address Action

engine/api/create_authorisation POST method, creates a new authorisation rule

engine/api/update_authorisation POST method, updates the authorisation rule

engine/api/read_authorisation POST method, reads authorisation rule

engine/api/read_authorisations POST method, reads all authorisation rules

engine/api/delete_authorisation POST method, deletes authorisation rule

engine/api/use_resource POST method, updates resource usage

http://localhost:9000/engine/api/create_authorisation

23


3.2.2 Create authorisation rule

The user can call create_authorisation service in order to register a new authorisation within the system. It is necessary to pass username, resource_category, resource_name, max and token parameters.

curl --data "username=testuser&resource_category=testresource&resource_name=testresourcename&max=5&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/create_authorisation

Response in the positive case:

{"success": "Rule successfully created."}

Response in the negative case:

{'error': 'Invalid rule'}

3.2.3 Update authorisation rule

The user can update authorisation information by calling the method update_authorisation. It is necessary to give new parameters that will replace old values.

curl --data "username=teste&resource_category=teste&resource_name=teste&max=20&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/update_authorisation


{"success": "Rule successfully updated."}


{'error': 'Rule not found.'}

3.2.4 Show authorisation rule

It is possible to retrieve the information of an authorisation rule by using methods read_authorisation and read_authorisations, as detailed next.

curl --data "username=teste&resource_category=teste&resource_name=teste&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/read_authorisation

24



{"success": "Rule information read successfully."}



It is also possible to show all rules:

curl --data "username=teste&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/read_authorisations


{"success": "Rules read successfully."}



3.2.5 Delete authorisation rule

A rule can be deleted from the AAA Manager by calling service delete_authorisation, which is responsible to remove underlying information from the database.

curl --data "username=teste&resource_category=teste&resource_name=teste&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/delete_authorisation


{"success": "Rule successfully deleted."}



3.2.6 Use resource

In order to use a resource, the user must call the use_resource service, which will verify whether the user has the necessary authorisation, and update subjacent accounting information, namely, incrementing the number of times such resource was used if it is less than the maximum allowed.

curl --data "username=teste&resource_name=teste&resource_category=teste&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/use_resource


{"success": "User is authorised."}


25


{'error': 'User is not authorised.'}

3.3 AAAaaS API for Accounting

The Accounting component records the interactions with the system. Working along with the Authorisation component, it registers the resources that are used, when they are used and by whom. This is useful not only for accountability but also for monetization of the system, if desired.

The system equally records messages related to the events in the following format:

"Resource " + resource_name + " used by: " + username


Table 3 describes the REST calls that can be made to the AAA accounting server API. The first column of the table shows the calls' address and the second shortly described the actions. The currently available method allows to read accounting information by using read_accounting.

Table 3: Accounting REST API endpoints

Address Action

engine/api/read_accounting POST method, reads accounting information of user

3.3.2 Read accounting

It is possible to read accounting information by calling service read_accounting, which returns the associated data.

curl --data "username=teste&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/read_accounting


{"success": "User accounting information read successfully."}


{'error': 'Accounting information not found.'}

26


3.4 Create Email Association

It is possible to associate a new email address to your profile, for example, in the case that the user has an academic email and a Gmail account. In order to do that the user may call service create_email. The email association is necessary to link different email addresses of the same user. This association can be done using the following URL:

https://eubrabigsea.dei.uc.pt/engine/api/create_email

curl --data "username=testreg&[email protected]&token=JDJiJDEyJGlBdm9kTmpid2I4eThqZU1zUnBHY2VkMjJQTklzMWJUWHR1Z2I2Zy4yZ3FGSnM0SEt6VERH" https://eubrabigsea.dei.uc.pt/engine/api/create_email

Responde in the positive case:

{"success": "Email association successfully created."}


{"error": ""}

3.4.1 Read Email Association

The user can read email associations by calling service read_emails.

curl --data "username=testreg&token=JDJiJDEyJGlBdm9kTmpid2I4eThqZU1zUnBHY2VkMjJQTklzMWJUWHR1Z2I2Zy4yZ3FGSnM0SEt6VERH" https://eubrabigsea.dei.uc.pt/engine/api/read_emails

Response in case that an email association exists:

{"data": [{"emails": [{"email": "[email protected]"}], "username": "testreg"}], "success": "Email association successfully read."}

Response in case there is no email associated:

{"data": [], "success": "Email association successfully read."}

3.4.2 Delete Email Association

To delete an email association, the user can call the delete_email service.

27


curl --data "username=testreg&[email protected]&token=JDJiJDEyJGlBdm9kTmpid2I4eThqZU1zUnBHY2VkMjJQTklzMWJUWHR1Z2I2Zy4yZ3FGSnM0SEt6VERH" https://eubrabigsea.dei.uc.pt/engine/api/delete_email


{"success": "Email association successfully deleted."}


{"error": "Invalid username."}

3.5 Favorites REST API endpoints

This functionality is used to store specific information about the favorite location of users. This feature was constructed to address a specific requirement from one of the EUBra-BIGSEA applications and may evolve in order to support more general data.

Table 4: Favorites REST API endpoints

Address Action

engine/api/create_favorite POST method, creates a new favorite

engine/api/read_favorite POST method, reads favorite of user

engine/api/read_favorites POST method, reads all favorites of user

engine/api/delete_favorite POST method, deletes favorite of user

3.5.1 Create Favorite

The method create_favorite is used to add favorite information to a user’s account. Its parameters for now are specific for this application, where city_id and country_id are integers.

curl --data "username=testuser&item_id=someitem&item_type=anytype&city_id=1&country_id=2&favorite_id=b&data=a

https://eubrabigsea.dei.uc.pt/engine/api/create_favorite

28


aatestfavoriteinfo&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/create_favorite


{"success": "Favorite association successfully created."}


{"error": "Invalid favorite."}

3.5.2 Read Favorite

Function read_favorite gets information from the database for some user and whose city_id and country_id is given as input, and returns as output the result of the query together with usual error and success messages.

curl --data "username=testuser&city_id=1&country_id=2&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/read_favorite


{"success": "Favorite association successfully read.", "data": "aaatestfavoriteinfo"}



3.5.3 Read all favorites from a user

The method read_favorites returns all favorites from a given user.

curl --data "username=testreg&token=JDJiJDEyJEFqVmdMR1pZVDVSQ0hZNVoxU1ZBcWVrZ1NFZnE4YVhZNlIxWVVKdmF3TTQudmNzcUp5bkht" https://eubrabigsea.dei.uc.pt/engine/api/read_favorites


{"data": [{"favorites": [{"city_id": 1, "favorite_id": "b", "item_id": "someitem", "item_type": "anytype", "country_id": 2, "data": "aaatestfavoriteinfo", "token": "JDJiJDEyJEFqVmdMR1pZVDVSQ0hZNVoxU1ZBcWVrZ1NFZnE4YVhZNlIxWVVKdmF3TTQudmNzcUp5bkht"}, {"city_id":




29


1, "favorite_id": "b", "item_id": "someitem", "item_type": "anytype", "country_id": 2, "data": "aaatestfavoriteinfoNUMBER2", "token": "JDJiJDEyJEFqVmdMR1pZVDVSQ0hZNVoxU1ZBcWVrZ1NFZnE4YVhZNlIxWVVKdmF3TTQudmNzcUp5bkht"}], "username": "testreg"}], "success": "Favorite association successfully read."}


{"error": "Invalid token"}

3.5.4 Delete Favorite

This function is used to remove favorite information from database.

curl --data "username=testuser&item_id=someitem&token=JDJiJDEyJGFaZkxSWC54WWVRVU1yWWZveWJUa2VnQklMRllVcUJWcU1FbmViLkRWRGdBamltejg2Ykou" https://eubrabigsea.dei.uc.pt/engine/api/delete_favorite


{"success": "Favorite association successfully deleted."}



3.6 Redirection Addresses and page layouts

Applications that need to use the authentication server login and register pages can do so by redirecting the users to the respective pages.

3.6.1 Login Page

Users are redirected to “https://eubrabigsea.dei.uc.pt/“. On the page shown in Figure 7, users can introduce their credentials (username and password). Once the login is successful, users are redirected back to the application which made the initial redirect.

https://eubrabigsea.dei.uc.pt/

30


Figure 7: Sign in Interface

If the user’s credentials are incorrect or do not match any record in the user’s database, an error message is presented (Figure 8).

Figure 8: Error message presented in the Interface

3.6.2 Sign Up Page

User are redirected to “https://eubrabigsea.dei.uc.pt/web/signup“. On the page presented in Figure 9, users can introduce their information: email, first name, last name, username and password. Once the fields are complete, the user presses the “Sign Up” button and a validation of the fields is performed.

https://eubrabigsea.dei.uc.pt/web/signup

31


Figure 9: Create new account Interface

All the fields are required for the signing up process. If the validation process detects that some fields do not contain the required information, warning message(s) are presented to the user in order to correct the information (Figure 10).

32


Figure 10: Warning examples

After all the fields contain the required information, the pressing of the “Sign Up” button requests the registration of the user in the database. If the username does not exist in the database, the registration

33


process is concluded with success. If the username already exists, then an error message is presented (Figure 11) and the user is asked to choose a different username.

Figure 11: Error Message - Sign up for a new account

34


3.7 Update user details

In addition to the available API methods, there is a dedicated web page for the user to access his/her information and update it, as well as to delete the account. Figure 12 presents this page, where the user signs in with his/her username and password. This page is accessible through:

https://eubrabigsea.dei.uc.pt/web/manage_info_auth

Figure 12: User information access

3.7.1 Update account details

After signing in successfully, the user is then redirected to a page with the account details and options to update them. The page layout is divided into four sections: user information (Figure 13), add secondary email (Figure 14), change password (Figure 15) and delete account (Figure 16).

https://eubrabigsea.dei.uc.pt/web/manage_info_auth

35


Figure 13: Account details interface

3.7.2 Add Secondary email

Users are allowed to add a secondary email address to their information. For this end, the interface presented in Figure 14 can be used.

36


Figure 14: Second Email Register

3.7.3 Change password

Users can also change their password. The standard use in these cases is to request the old and new password, the latter needed to be confirmed. Figure 15 presents this interface.

Figure 15: Update password information

37


3.7.4 Delete user account

To permanently delete the user account, the user needs to sign in and afterwards, using the delete account page (Figure 16), press the button "Delete Account".

Figure 16: Delete Account

A confirmation prompt box (Figure 17) is displayed to make sure the user wants to delete the account. After clicking “OK” the action takes place and the account is permanently deleted.

Figure 17: Confirmation for Deleting Account

3.7.5 Reset Password

When the user forgets the password and wants to reset it, he/she can do so using a graphical interface (Figure 18), as well through https://eubrabigsea.dei.uc.pt/web/signin_options.

https://eubrabigsea.dei.uc.pt/web/signin_options

38


Figure 18: Reset Password Interface

3.7.6. Resend Confirmation Email

Located on the same page as the previous point, there is the option of sending the confirmation email necessary for the sign-up process again. This can be useful if, for some reason, the user does not receive the email or no longer has it. For that, the user introduces the username and the email used during the signup process (Figure 19). This option is available at https://eubrabigsea.dei.uc.pt/web/signin_options.

https://eubrabigsea.dei.uc.pt/web/signin_options

39


Figure 19: Resend Email Confirmation Account

3.8 Configuration for redirects (popup’s)

A configuration code is required when the developers use the AAAaaS Graphical User Interface. This module works as a popup window called by the developer’s application(s). The examples presented in the next sections demonstrate how to make the call.

When the popup is open, the user is redirected to AAAaaS webpage. From there, the user can sign in, sign up, change information, update password and others. After completing the action, the user is redirected back to the application’s webpage and the application receives the answer to the request that was made.

For this setup to work, two functions need to be added. The first (openWin()) opens the popup window of the AAAaaS. The second (HandlePopupResult()) handles the answer given by AAAaaS.

The following two sections contain examples for the Sign In and Sign Up methods. Nevertheless, the process is identical for other functionalities.

40


3.8.1 Button to create popup with “Sign In” page

This step creates a button which opens a popup window (or new tab) with EUBra-BIGSEA authentication page. In the developer’s application(s), it is necessary to create a button pointing to the EUBra-BIGSEA authentication page. Following there is an HTML example:

<input type="button" value="Open window" onclick="openWin('https://eubrabigsea.dei.uc.pt'); return false;" />

The function “openWin” (in the previous example) is called with the address of the EUBra-BIGSEA authentication page as a parameter (https://eubrabigsea.dei.uc.pt).

To receive the answer of the popup page, a JavaScript function is needed (as well as the openWin function to create the popup). The following code should be in the Javascript file associated with the webpage of the app. Please note that the function “HandlePopupResult” is the one handling the answer.

function openWin(url, w, h)

{

console.log('openwindow');

var left = (screen.width/2)-(w/2);

var top = (screen.height/2)-(h/2);

w=window.open(url, '_blank');

w.focus();

}

var answer_data;

// answer_data is the variable that will contain the answer from the popup page

function HandlePopupResult(answer_data) {

console.log('Received the answer!');

console.log(answer_data); This displays in the console the received JSON answer

//From here, take care of answer. Do your logic with the returned JSON

}

The format of the JSON answers are described in section 3.1.2 - Authentication.

https://eubrabigsea.dei.uc.pt/

41


3.8.2 Button to create popup with “Sign Up” page

This second step creates a button which opens a popup window (or new tab) with EUBra-BIGSEA sign up page.

In the application, create a button pointing to the “Sign Up” page, such as in the following example:

<input type="button" value="Open window" onclick="openWin('https://eubrabigsea.dei.uc.pt/web/signup'); return false;" />

The function “openWin” is called with the address of the “Sign Up” page as a parameter (https://eubrabigsea.dei.uc.pt/web/signup ).

To receive the answer of the popup page, a JavaScript function is needed (as well as the openWin function to create the popup). The following code should be in the Javascript file associated with the webpage of the app. Please note that the function “HandlePopupResult” is the one handling the answer.

function openWin(url, w, h)

{

console.log('openwindow');

var left = (screen.width/2)-(w/2);

var top = (screen.height/2)-(h/2);

w=window.open(url, '_blank');

w.focus();

}

var answer_data;

// answer_data is the variable that will contain the answer from the popup page

function HandlePopupResult(answer_data) {

console.log('Received the answer!');

console.log(answer_data); This displays in the console the received JSON answer

//From here, take care of answer. Do your logic with the returned JSON

}

The format of the JSON answers is described in the “Sign Up” section.

https://eubrabigsea.dei.uc.pt/web/signup

42


3.9 External Login with Google

The external login feature enables the user to login and use an application without having a local account. For that the Google Sign In service is used, with the user introducing his email and password from Google. When the user gets to the authentication window, he is presented with the options below. In the first case, by clicking “Sign in” (Figure 20), he/she will be redirected to a Google Login Page to enter his/her credentials. Eventually, the user will be automatically signed in a login was made before and the session is saved by the browser. In this last case Google alerts the user that she / he is signed in (Figure 21).

Figure 20: Google Interface to Sing in

In any case, the option to sign out is always available by clicking the “Sign out from Google” link.

Figure 21: Signed in Alert by Google

Regarding this integration with Google services, two points should be mentioned.

First, the fact that Google requires an email account to be associated with the External Login service. This means a global, previously defined email needs to be active and managed when an application uses this kind of service. This is a characteristic of how Google currently offers the service which the application developer/manager needs to be aware of when deploying and using the AAAaaS service.

43


Second, the existence of two different options to handle user’s data. One of the options is to save the user’s data at the AAAaaS server, and the other is to send the Google ID token to the application and then let the application interact directly with Google for accessing user data. Each of these options fits different usage scenarios, depending on the AAAaaS deployment model (e.g. shared/dedicated service), possible legal constraints on handling user’s data related with specific applications/countries, etc.

3.10 Initialization of services

The AAAaaS is formed by a set of three different Docker containers: a web server, a web application and a database. On a low level (Docker and system interaction) each container is always started individually. However, on a higher level (e.g. user interaction) the containers can be launched manually one by one or sequentially with Docker-compose. Following there is a presentation of each case, as well as respective instructions.

3.10.1 Dockerfile (single components)

In the scenarios where there is a single server hosting the AAAaaS, it is necessary to create a Docker network specific for the containers to be launched. This is due to the need of communication between the different containers. With this prerequisite, the containers are launched associated to the previously created Docker network.

Following, there are the instructions to create the Docker network. In this example, the network’s name is “testnet”, operating in bridge mode, IP subnet 172.250.0.0/24 and gateway 172.250.0.1.

Create network: # docker network create --driver=bridge --subnet=172.250.0.0/24 --gateway=172.250.0.1 testnet

After creating the Docker network, the containers are launched with IP addresses matching the range of docker network and respective port mapping for communications. Additionally, the hostname for each container is set. This is how the services are able to discover each other and communicate.

Launch web server: # docker run --name nginx --ip=172.250.0.86 --net=testnet -p 80:80 -p 443:443 -p 8080:8080 -ti paulo308/aaaaas_webserver Launch database: # docker run --name mongo --ip=172.250.0.88 --net=testnet -p 27017:27017 -ti -h mongo paulo308/aaaaas_mongodb Launch web application: # docker run --name webapp --ip=172.250.0.85 --net=testnet -p 9000:9000 -ti paulo308/aaaaas_webapp

44


3.10.2 Docker-compose (sequentially)

There are cases where the AAAaaS is being deployed on a server that supports Docker-compose. This component allows the initialisation of several Docker containers with dependencies using a single configuration file.

In this case, it is necessary to have a configuration file (docker-compose.yml) which defines all the services parameters and their dependencies. To start, you need to give the proper permissions to "start.sh" script:

chmod +x start.sh

After that, you can run the script which will delete all the Docker containers in the system and make a clean install. Make sure to setup a proper environment to keep any previously created Docker container. If a clean install is not necessary, the “start.sh” script can be modified accordingly. To run the script:

./start.sh

After the execution of the script, all the containers should be active and operational.

3.10.3 Marathon

In a case where the services are to be launched by a Marathon framework, there are certain aspects to consider. Currently, a Marathon/Mesos powered infrastructure does not allow the naming of a service. This means that the containers cannot discover themselves through a previously defined hostname. They should communicate through IP address.

There is a script developed exclusively to make use Mesos-DNS endpoint and retrieve IP address and port of a certain container. However, the current versioning of the AAAaaS does not support dynamic configuration due to security issues. Even though IP address and ports can be retrieved, it is not possible to dynamically issue the certificates. The reason is that the database connection certificates are currently generated by CFSSL (CloudFlare's PKI toolkit) using hostnames. A future update will tackle this issue.

Nevertheless, the service can be manually deployed on such infrastructures by following the instructions mentioned in Dockerfile section.

Considering the scenario where the previously described situation is solved, there are steps to follow to launch the services by marathon. First, an overlay network with global scope needs to be created on the infrastructure. To do so, for this example, the network’s name is “aaanet”, the driver is overlay, and the subnet is 172.250.0.0/24.

sudo docker network create --driver overlay --subnet=172.250.0.0/24 --gateway=172.250.0.1 aaanet

45


Secondly, the services can be launched by Marathon. Since Marathon uses JSON files for the configuration parameters, the following examples are the JSON files of the three services: database, web application and web server, respectively. The order should be the same due to dependencies.

Database:

{

"id": "/auth/auth-db",

"cmd": null,

"cpus": 1,

"mem": 999,

"disk": 3000,

"instances": 1,

"container": {

"docker": {

"image": "eubrabigsea/aaaaas_db",

"forcePullImage": true,

"network": "USER",

"portMappings": [

{

"containerPort": 27017,

"hostPort": 27017,

"protocol": "tcp",

"name": "27017",

"labels": null

}

],

"parameters": [

{ "key": "ip", "value": "172.250.0.88" },

{ "key": "hostname", "value": "mongo"}

]

},

"type": "DOCKER"

},

"ipAddress": {

"networkName": "aaanet"

}

}

Web application:

{

46


"id": "/auth/auth-webapp",

"cmd": null,

"cpus": 1,

"mem": 999,

"disk": 3000,

"instances": 1,

"container": {

"docker": {

"image": "eubrabigsea/aaaaas_webapp",


"network": "USER",

"portMappings": [

{


"hostPort": 0,

"protocol": "tcp",

"name": "9000",

"labels": null

}

],

"parameters": [

{ "key": "ip", "value": "172.250.0.85" },

{ "key": "hostname", "value": "webapp"}

]

},

"type": "DOCKER"

},

"ipAddress": {


}

}

Web server:

{

"id": "/auth/auth-webserver",

"cmd": null,

"cpus": 1,

"mem": 999,

"disk": 3000,

47


"instances": 1,

"container": {

"docker": {

"image": "eubrabigsea/aaaaas_webserver",


"network": "BRIDGE",

"portMappings": [

{


"hostPort": 0,

"protocol": "tcp",

"name": "80",

"labels": null

},

{


"hostPort": 0,

"protocol": "tcp",

"name": "443",

"labels": null

},

a. {


"hostPort": 0,

"protocol": "tcp",

"name": "8080",

"labels": null

}

],

"parameters": [

{ "key": "ip", "value": "172.250.0.86" },

{ "key": "hostname", "value": "nginx"}

]

},

"type": "DOCKER"

},

"ipAddress": {


}

48


}

3.11. Summary

The functionalities provided by AAAaaS API were presented in this chapter, along with examples for each one of the currently available endpoints. The examples demonstrate functionalities transversal to authentication, authorisation and accounting for applications. It was equally demonstrated the favorites functionalities that may be associated with each user.

The next chapter presents the Infrastructure API (iAA API) and providers examples of its usage.

4. INTERACTION WITH THE IAA API

Like in the AAAaaS module, the iAA module was designed to allow a straightforward adaptation in context of cloud computing. Sharing similarities with the AAAaaS, it allows an interaction both from API endpoints and Graphical User Interface (GUI).

4.1. REST API Endpoints

Table 5 describes the REST calls that can be made to the iAA server API. The first column of the table shows the calls' address and the second shortly describes the actions. The currently available methods allow to checkin and insert data of users’ credentials in the infrastructure.

Table 5: REST calls available in the iAA server API

Address Action

engine/api/checkin_data_infra POST method, verifies credentials and provides user infrastructure credentials

engine/api/insert_data_infra POST method, inserts users’ credentials for infrastructure

4.2. Infrastructure Authentication

This feature allows the infrastructure to verify if a specific user account contains credentials for infrastructure access. The verification is made with a sign in-like workflow.


https://eubrabigsea.dei.uc.pt/engine/api/verify_token

49


The verification requires a username and password. Then, the endpoint verifies if the user is correctly authenticated and if it has the necessary credentials (i.e. permissions) to access the infrastructure. Following are presented examples of request and response in the positive and negatives case when check-in for infrastructure is invoked. curl --data "username=testuser&pwd=aB123456" https://eubrabigsea.dei.uc.pt/engine/api/checkin_data_infra Response in the positive case: {"success": "Infra data successfully read.", "data": [{"username": "testuser", "data": [{"secret": "secret", "principal": "principal"}]}]} Responses in the negative case: {"error": "Please confirm your account. Check your inbox or spam folders."} {'error': 'Invalid username.'} {"error": ""}

4.3. Insert data for infrastructure authentication (for administrators use)

This feature allows an administrator to insert the infrastructure credentials on a specific user account. This is the set of credentials to be verified by the previous endpoint (checkin_data_infra). The current version does not specify who is the actor in charge of such a task. A future implementation will present a fine-grained control on who can introduce the credentials (e.g. only administrators). curl --data "username=testuser&principal=principal&secret=secret" https://eubrabigsea.dei.uc.pt/engine/api/insert_data_infra Response in the positive case: {"success": "Infra data successfully created."} Responses in the negative case: {"error": "Please confirm your account. Check your inbox or spam folders."} {'error': 'Invalid username.'}

4.4. Summary

In this Section 4 we presented the Infrastructure API (iAA) services, which share several modules with the AAAaaS module. The following chapter refers to the integration with the different partners.

https://eubrabigsea.dei.uc.pt/engine/api/checkin_data_infra






50


5. INTEGRATION OF SERVICES

There are several EUBra-BIGSEA applications and modules integrated and working with the AAA service. Melhor Busão and Routes for People are two applications that use the Authentication, Authorization and Accounting services provided by the AAA module. The broker, which is the entry point for running tasks at the infrastructure, also uses the AAA service to authenticate and authorize its users before letting tasks proceed to execution. The cluster deployed at UPV is also part of the integration work.

Following, there is a section for each one of the aforementioned modules. In each section, the type of integration made and the status at the moment of writing of this document will be described.

5.1. Melhor Busão

Melhor Busão is an example of integration of an application exclusively through the REST API. The application has its own user interfaces and performs the AAA requests based on what is necessary or not, for the functioning of their application. This kind of flexibility is valuable since not every application need all the features and functionalities.

Melhor Busão has the basic authentication features integrated: sign in, sign up, verify token, sign out and others. As additional features might be needed, it has the flexibility to use any of the endpoints currently available.

5.2. Routes for People

Routes for People is an example of an application that uses both types of AAA resources. It uses the REST API endpoints as well as the Graphical User Interface (GUI) provided. As the users access the Routes for People webpage, when they click sign in, or sign up, they are redirected to the AAA frontend (the Graphical User Interface). This requires an integration work on both sides (application and AAA service). It is necessary to handle popup pages on the browsers, to handle requests and respective answers.

Apart from handling the popup pages where the AAA service is presented, there is a wide variety of features being used by this application. Features like token verification, “stay-signed-in” option or sign out are integrated with the REST API. Features like user favorites are also being used. With this, a user of Routes for People application can have an account to use that application as well as save favorites (e.g. routes or cities) to use later.

This application is an example of seamless integration of both ends of the service: REST API and user interface. This saves the developer time and effort to develop user interface.

5.3. Broker

The broker, as an intermediary between user and infrastructure, acts like a checkpoint. By receiving the jobs or tasks, the broker needs to decide whether or not to let the requests go through. To do that, the AAA service and its REST API endpoint is used.

The broker makes requests to the AAA service as if in each request, a sign in is demanded. The sign in authenticates the user. A successful signin gives the broker the information that the user exists and is valid. Regarding authorization and accounting, it is optional for the broker to use it or not.

51


5.4. UPV Cluster

Regarding the integration with UPV’s cluster, it is currently possible to launch services manually and without HTTPS. The scenario where the deployment is semi-automatic (and using Marathon) is currently not yet fully deployed. Due to recent integration issues, it was not yet possible to fully automate the system for a multi-node cluster as on a single-node system (like with the current version of AAAaaS). Nonetheless, the system can be already deployed on the Front/End node and the complete solution for automated deployment should become ready soon, once Mesos-related issues are solved.

These issues are related with container naming by Mesos and SSL certificates. Since Mesos does not allow one to specifically name a container (Mesos does it automatically), it was necessary to modify the AAAaaS to dynamically handle different names for the containers. Also, the location is dynamic due to the ability of Mesos to launch the container on any of the available agent nodes. Thereby, it is currently being developed an update where each service component can not only discover where other components are launched, but how to discover them in case they’re assigned to a different agent node. This is to make the system able to use SSL certificates both on client-server connections and server-database connections. This is necessary to provide higher security standards within the system.

Following, there is an example of the deployment of the database component on the cluster. The following command needs to be executed:

# docker run --name mongo --ip=172.250.0.88 --net=bigsea_net -p 27017:27017 -ti -h mongo eubrabigsea/aaaaas_db

If the container image does not exist locally, it is pulled from the “eubrabigsea” repository on DockerHub. Figure 21 shows the execution of the command and respective pulling from DockerHub’s repositories.

Figure 21: Launching Database container from DockerHub

After downloading all the necessary layers to launch the container, the service (in this case, the database) becomes active and waiting form connections from the web application (Figure 22).

52


Figure 22: Database container launched and waiting for connections

The procedures to make the system operational are similar and simple. After repeating the steps previously demonstrated, this time for the remaining components (web application and web server), it is necessary to redirect the service to the ports assigned to the AAA service. The port assigned for the service to be externally accessible is 8050. With this, the last step is to perform a “redir” command to map ports and IP addresses:

# sudo redir --laddr=158.42.105.24 --lport=8050 --caddr=158.42.105.24 --cport=443

In this example, the port being redirect is the 443 from the web server component (assigned for HTTPS requests). However, the example depicted in Figure 23 shows the web interface without HTTPS certificates activated. This is the reason why the browser presents the “Not Secure” warning on the top left corner.

Figure 23: Web interface of service launched on cluster (158.42.105.24) without HTTPS

On the other hand, for demonstration purposes, the currently active service has all the security features activated and functional. It is currently deployed at eubrabigsea.dei.uc.pt. The examples used before in this

53


document are from the service that is running on the eubrabigsea.dei.uc.pt server. Figure 23 shows the current web interface of the AAA service.

Figure 24: Web interface of service launched on DEI server (eubrabigsea.dei.uc.pt) with HTTPS

5.5. Summary

As it was described, there are already several types of integration with the AAA modules. Each one with specific requirements and particularities. Nevertheless, it is a demonstration of the integration capabilities of the service. There is work to do in cases like the UPV cluster integration. However, it is something currently being solved and ready to be demonstrated and released soon. Following, the final considerations and next steps for this work.

54


6. FINAL CONSIDERATIONS AND NEXT STEPS

Considering that the AAA components of the EUBra-BIGSEA project must integrate with other components, from different abstraction layers, it was crucial to begin with a simple API, designed to fit the specific necessities of other teams, and at the same time respecting important architectural decisions. The AAA library evolved to the proposal described here in this document, offering both a web interface and REST API, which has been deployed and successfully running in the EUBra-BIGSEA testbeds for some time.

These AAA components are currently integrated both with the underlying infrastructure and a number of EUBra-BIGSEA applications, providing a stable and adequate set of functionalities for supporting AAA services on both perspectives. Nevertheless, the team responsible for the AAA components intends to take advantage of the remaining time in the project to further refine these services, for instance implementing automatic generation of certificates to allow the on-demand HTTPS deployment of the AAA system and a more extensive interface for administration of AAA services.

55


REFERENCES

[1] J. Bonneau, C. Herley, P. C. v. Oorschot and F. Stajano, "The Quest to Replace Passwords: A Framework for Comparative Evaluation of Web Authentication Schemes," 2012 IEEE Symposium on Security and Privacy, San Francisco, CA, 2012, pp. 553-567.

[2] A. J. Choudhury, P. Kumar, M. Sain, H. Lim and H. Jae-Lee, "A Strong User Authentication Framework for Cloud Computing," 2011 IEEE Asia-Pacific Services Computing Conference, Jeju Island, 2011, pp. 110-115.

[3] Umer Khalid, Abdul Ghafoor, Misbah Irum, Muhammad Awais Shibli, Cloud Based Secure and Privacy Enhanced Authentication & Authorization Protocol, Procedia Computer Science, Volume 22, 2013, pp. 680-688.

d6.2: aaa provisioning services and mechanisms · 2018-04-10 · gui screenshots, onfiguration...

Documents