BrainPEP

Overview

BrainPEP is a back-end that offers RESTful API that follows OpenAPI Specification. It is the main component used for deciding and enforcing whether a data consumer service is authorized to receive data in transit. It is configured as the main OAuth2 Resource Manager in charge of handling the catalogue of the overall system-enabled services. Its scope is to manage the resources associated to Services and Devices interacting with an Identity and Access Manager i.e. Keycloak.

For more information click the image below

Installation

Prerequisites

1. Install Docker

2. Install PostgreSql

3. Install Nginx The service presume you have nginx installed, and the root path assigned to the Back-end is /brainpep

Clone the repository

$ git clone https://github.com/eclipse-researchlabs/brain-iot-privacy-control-system-api

Configuration

The service assume that you have a Keycloak instance running in a host, so before proceed with the configuration of the environment variables you must configure Keycloak

Keycloak

• Build a Keycloak realm (i.e. Brainiot) via administration GUI

• Define two realm roles to be assigned at base users and service providers (i.e. brain_user and brain_consumers).

• Build a confidential client to be assigned at the backend (i.e. brain_pep).

  • Assign to the brain_pep client the set of roles of interest that will be exploited as policies foreseen by the system (enabled for base-users devices).
  • Define the same set of policies as authorization scopes of the resources managed by the brain_pep client (enabled for service providers).

• Build a public client to be exploited by the Privacy dashboard (i.e. client_pub).

  • Define for it Valid Redirect URIs and Web Origins as detailed in the dashboard Readme.
  • Enable Standard Authentication Flow for it (OAuth2 authorization-code).

• Build the base-users of interest and assign them the Keycloak role defined (brain_user).

• Build the service-providers-users of interest and assign them the Keycloak role defined (brain_consumers).

From now on, it will be possible to start interacting via APIs or dashboard to characterize the devices and the services enabled by the conceived scenario.

In particular, the base-users will be able to:

• login to the dashboard exploiting the keycloak-user credentials
• add new personal devices and define for each one of them specific policies

The Service-providers-users will be able to:

• login to the dashboard exploiting the keycloak-user credentials
• add new services and define for each one of them the policies applied

Finally, the distributed gateways integrated with the Privacy system will be enabled to:

• request for a signed token containing the latest policies applied to a device pushing data
• request for a remote analysis (executed on Brain-PeP) to grant forwarding of each incoming message towards the locally connected services by evaluating at real time the policies defined

File .env

Before building the container, set the right values to the settings inside .env file. The settings can be divided in:

1. Security
2. Admin Keycloak Credentials
3. BrainPEP
4. Database
5. Gunicorn

Security

Variable	Description	Example
ALGORITHM	Encryption algorithm used for decode JWT	"RS256"
AUDIENCE	Audience associated to the JWT	"client"
ISSUER	Url of who emitted the token	"https://aut-server.it/auth/realms/Brainiot"
JWS_ALGORITHM	Encryption algorithm used for decode JWS	"RS256"
JWS_PRIVATE_KEY	Private cryptography key used for sign JWS	"MIIEogIBAAKCAQEArVxYJPkQejSCMdgKuuW/STuk...."
JWS_PUBLIC_KEY	Public cryptography key used for decode JWS	"MIIEogIBAAKCAQEArVxYJPkQejSCMdgKuuW/STuk...."
REALM_PUBLIC_KEY	Public cryptography key used for decode JWT	"MIIEogIBAAKCAQEArVxYJPkQejSCMdgKuuW/STuk...."

Admin Keycloak Credentials

Variable	Description	Example
ADMIN_CLIENT_ID	Identifier of keycloak administrator	"My identifier"
ADMIN_CLIENT_SECRET	Secret associated to the administrator	"my super secret"
ADMIN_GRANT_TYPE	Typology of grant associated to the administrator	"password"
ADMIN_PASSWORD	Password associated to the administrator	"super_secret"
ADMIN_TOKEN_REQUEST_URL	Url to request a token for the administrator (must be in the master realm)	"http://auth-server.it/auth/realms/master/protocol/openid-connect/token"
ADMIN_USERNAME	Administrator username	"brainadmin"

BrainPEP

Variable	Description	Example
CLIENT_ID	Identifier of brainpep client on keycloak	"My identifier"
CLIENT_GRANT_TYPE	Typology of grant associated to the brainpep	"password"
CLIENT_SECRET	Secret associated to brainpep (it's an uuidv4 given by keycloak)	"6209377f-589e-439b-8278-ccd2965fb304"
CLIENT_PASSWORD	Password associated to brainpep	"super_secret"
CLIENT_TOKEN_REQUEST_URL	Url to request a token for brainpep (must be in brainiot realm)	"http://auth-server.it/auth/realms/Brainiot/protocol/openid-connect/token"
RESOURCE_REQUEST_URL	Url to interact with the resources associated to brainpep	"http://auth-server.it/auth/realms/Brainiot/authz/protection/resource_set"
POLICY_REQUEST_URL	Url to interact with keycloak to store the device policies in uud4 format	"http://auth-server.it/auth/admin/realms/Brainiot/clients/{CLIENT_SECRET}/roles"
USER_ATTRIBUTE_REQUEST_URL	Url to set user attributes on keycloak	"http://auth-server.it/auth/admin/realms/Brainiot/users"

Database

Variable	Description	Example
CONNECTION_NUMBER	Number of connection instantiated	20
POSTGRES_DB	Database name	"brain_data"
POSTGRES_PORT	Port to use	5432
POSTGRES_PWD	Database password	"my_password"
POSTGRES_USER	User Associated to the database	"postgres"

Gunicorn

Variable	Description	Example
LOG_LEVEL	Logging level	"WARNING"
CORES_NUMBER	Host cores number	8
KEEP_ALIVE	Max seconds for receive keep alive	5432
SERVER_PORT	Port exposed by the server	8000
DATABASE_MAX_CONNECTION_NUMBER	Max connections handled by the system (100 by default for postgres) (15 are reserved for the admin)	"postgres"
MAX_WORKERS_NUMBER	Max number of worker processes	9
TIMEOUT	Time without actions before restart a worker process	"my_password"

Build

~$ cd brain-iot-privacy-control-system-api
~$ docker build . -t brainiot/brainpep:1.0.0 

Run

~$ docker run -d --net my_network --ip brain_pep_ip --name brainpep brainiot/brainpep:1.0.0

Benchmarks

To ensure the reliability of the system it was run a benchmark simulating 100 gateways sending packets in cascade for 20 seconds in the production environment, and it was calculated the latency of the responses and if every response was successful.

For more information and stats click the image below