Merge branch 'master' of https://github.com/Engineering-Research-and-…

…Development/fiware-true-connector.git

README.md

@@ -1,8 +1,13 @@
 # TRUE CONNECTOR
+
 [![License: AGPL](https://img.shields.io/github/license/Engineering-Research-and-Development/fiware-true-connector.svg)](https://opensource.org/licenses/AGPL-3.0)
+[![CI](https://github.com/Engineering-Research-and-Development/true-connector-execution_core_container/workflows/ECC/badge.svg)](https://github.com/Engineering-Research-and-Development/true-connector-execution_core_container/actions/workflows/ECC.yml)
+[![Documentation badge](https://readthedocs.org/projects/fiware-true-connector/badge/?version=latest)](https://fiware-true-connector.readthedocs.io/en/latest/)
 <br/>
 **TRUE** (**TRU**sted **E**ngineering) **Connector** for the IDS (International Data Space) ecosystem
 
+The FIWARE TRUE Connector enables the trusted data exchange in order to be active part of an IDS Ecosystem, a virtual data space leveraging existing standards and technologies, as well as governance models well-accepted in the data economy, to facilitate secure and standardized data exchange and data linkage in a trusted business ecosystem. The connector is compliant with the latest IDS specifications and can be easily customized to fit a wide spread of scenarios thanks to the internal separation of Execution Core Container and Data App. It is integrable with a lot of existing IDS services and totally configurable in terms of internal/external data format (multipart/mixed, multipart/form, http-header) and protocols (HTTP, HTTPS, Web Socket over HTTPS, IDSCPv2).
+
 The TRUE Connector is composed of three components:
 
 * [Execution Core Container (ECC)](https://github.com/Engineering-Research-and-Development/true-connector-execution_core_container), open-source project designed by ENG. It is in charge of the data exchange through the IDS ecosystem representing data using the IDS Information Model and interacting with an external Identity Provider. It is also able to communicate with an IDS Broker for registering and querying information.
@@ -11,146 +16,8 @@ The TRUE Connector is composed of three components:
 
 ![TRUE Connector Architecture](docs/img/TRUE_Connector_Architecture.png?raw=true "TRUE Connector Architecture")
 
-| :books: [Documentation](https://true-connector.rtfd.io) | :whale: [Docker Hub](https://hub.docker.com/) | :dart: [Roadmap](https://github.com/Engineering-Research-and-Development/fiware-true-connector/blob/master/roadmap.md) |
-| ------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-
-## How to Configurate and Run
-
-The configuration should be performed customizing the following variables in the **.env** file:
-
-* **DATA_APP_ENDPOINT=192.168.56.1:8084/data** DataAPP endpoint for receiveing data (F endpoint in the above picture)
-* **MULTIPART_EDGE=mixed** DataAPP A-endpoint Content Type (choose *mixed* for Multipart/mixed or *form* for Multipart/form-data or *http-header* for Multipart/http-header) 
-* **MULTIPART_ECC=mixed** Execution Core Container B-endpoint Content Type (choose *mixed* for Multipart/mixed or *form* for Multipart/form-data or *http-header* for Multipart/http-header) 
-* Edit external ports if need (default values: **8086** for **WS over HTTPS**, **8090** for **http**, **8889** for **B endpoint**, **29292** for **IDSCP2**)
-* Forward-To protocol validation can be changed by editing **application.validateProtocol**. Default value is *true* and Forward-To URL must be set like http(https,wss)://example.com, if you choose *false* Forward-To URL can be set like http(https,wss)://example.com or just example.com and the protocol chosen (from application.properties)will be automatically set (it will be overwritten! example: http://example.com will be wss://example if you chose wss in the properties).
-* For websocket configuration, in DataApp resource folders, configure *config.properties* file, set following fields
-
-```
-server.ssl.key-password=changeit
-server.ssl.key-store=/cert/ssl-server.jks
-```
-Or leave default values, if certificate and its password are correct.
-
-### Supported Identity Providers
-
-If it is needed to run the connector in developer mode please set the following properties as false:
-
-```
-CACHE_TOKEN=false
-FETCH_TOKEN_ON_STARTUP=false
-application.isEnabledDapsInteraction=false
-```
-
-This allow you to skip  the Daps interaction during the process in the development phase, otherwise you need to have a certificate provided from the CA offering Identity provider service.
-
-
-The TRUE Connector is able to interact with the following Identity Providers:
-
-* **AISECv1** put the certificate in the *cert* folder, edit related settings (i.e., *application.keyStoreName*, *application.keyStorePassword*) (in the *.env*) and set the *application.dapsVersion* (in the *resources/application-docker.properties*) to *v1*
-* **AISECv2** put the certificate in the *cert* folder,edit related settings (i.e., *application.keyStoreName*, *application.keyStorePassword*) (in the *.env*) and set the *application.dapsVersion* (in the *resources/application-docker.properties*) to *v2*
-* **ORBITER** put the certificate in the *cert* folder, edit related settings (i.e., *application.daps.orbiter.privateKey*, *application.daps.orbiter.password*) (in the *.env*) and set the *application.dapsVersion* (in the *resources/application-docker.properties*) to *orbiter*
-
-
-The *application.dapsUrl* (in the *resources/application-docker.properties*) property must be set properly in order to address the right DAPS server.
-
-Finally, run the application:
-
-*  Execute `docker-compose up &`
-
-## Endpoints
-The TRUE Connector will use two protocols (http and https) as described by the Docker Compose File.
-It will expose the following endpoints:
-
-```
-/proxy 
-```
-to receive data incomming request, and based on received request, forward request to Execution Core Connector (the P endpoint in the above picture)
-
-``` 
-/data 
-```
-to receive data (IDS Message) from a sender connector (the B endpoint in the above picture)
-Furthermore, just for testing it will expose (http and https):
-
-```
-/about/version 
-```
-returns business logic version 
-
-## Configuration
-The ECC supports three different way to exchange data:
-
-*  **REST endpoints** enabled if *WS_EDGE=false* and *WS_ECC=false*
-*  **IDSCP2** enabled if *IDSCP2=true* and WS_ECC = false </br>For *WS_EDGE=true* (use websocket on the edge, false for REST on the edge) 
-*  **Web Socket over HTTPS** enabled if *WS_EDGE=true* and *WS_ECC=true* and *IDSCP2=false* for configuration which uses web socket on the edge and between connectors.
-
-For trusted data exchange define in *.env* the SSL settings:
-
-*  KEYSTORE-NAME=changeit(JKS format)
-*  KEY-PASSWORD=changeit
-*  KEYSTORE-PASSWORD=changeit
-*  ALIAS=changeit
-
-## How to Test
-The reachability could be verified using the following endpoints:
-
-*  **http://{IP_ADDRESS}:{HTTP_PUBLIC_PORT}/about/version**
-
-Keeping the provided docker-compose, for Data Provider URL will be:
-
-*  **http://{IP_ADDRESS}:8090/about/version**
-
-For Data Consumer, with provided docker-compose file:
-
-*  **http://{IP_ADDRESS}:8091/about/version**
-
-
-## How to Exchange Data
-
-For details on request samples please check following link [Backend DataApp Usage](https://github.com/Engineering-Research-and-Development/market4.0-data_app_test_BE/blob/master/README.md)
-
-Be sure to use correct configuration/ports for sender and receiver Data App and Execution Core Container (check .env file).
-
-Default values:
-
-```
-DataApp URL: https://{IPADDRESS}:8084/proxy 
-"Forward-To": "https://{RECEIVER_IP_ADDRESS}:8889/data",
-```
-
-For WSS flow:
-
-```
-DataApp URL: https://{IPADDRESS}:8084/proxy
-"multipart": "wss",
-"Forward-To": "wss://ecc-provider:8086/data",
-"Forward-To-Internal": "wss://ecc-consumer:8887",
-```
-
-### WebSocket 
-
-On the following link, information regarding WebSocket Message Streamer implementation can be found here [WebSocket Message Streamer library](https://github.com/Engineering-Research-and-Development/market4.0-websocket_message_streamer).
-
-#### IDSCP2
-Follow the REST endpoint or WS examples, put the server hostname/ip address in the Forward-To header (*wss/https://{RECEIVER_IP_ADDRESS/Hostname}:{WS_PUBLIC_PORT}*).
-* **AISECv2** put the certificates (keyStore and trustStore) in the *cert* folder,edit related settings (*IDSCP2 AISEC DAPS settings* section in env file)
-
-
-## Clearing House
-
-The TRUE Connector supports is able to communicate with the ENG Clearing House for registering transactions. 
-
-## Broker
-
-The TRUE Connector integrates some endpoints for interacting with an IDS Broker described in [Broker](https://github.com/Engineering-Research-and-Development/fiware-true-connector/blob/master/docs/broker.md) section
-
-## Usage Control
-The TRUE Connector integrates the [Fraunhofer MyData Framework](https://www.mydata-control.de/) for implementing the Usage Control. Details about the PMP and PEP components can be found [here](docs/usage_control_rules.md). 
-
-## Contract Negotiation - simple flow
-
-For simple contract negotiation flow, with ContractAgreement read from file, please check following link
-[Data App Contract Negotiation](https://github.com/Engineering-Research-and-Development/true-connector-basic_data_app/blob/master/README.md#markdown-header-Contract-Negotiation-simple-flow) 
+| :books: [Documentation](https://fiware-true-connector.readthedocs.io/en/latest/) | :whale: [Docker Hub](https://hub.docker.com/) | :dart: [Roadmap](https://github.com/Engineering-Research-and-Development/fiware-true-connector/blob/master/roadmap.md) |
+| -------------------------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
 
 
 ## License

docs/true_connector_tutorial.md

@@ -1,17 +1,63 @@
 # TRUE Connector Tutorial
 
-This is a step-by-step tutorial that will introduce in detail how to exchange data in a trusted environment using the TRUE Connector
+This is a step-by-step tutorial that will introduce in detail how to exchange data in a trusted environment using the TRUE Connector.
 
 ## What is IDS?
 
 The International Data Space (IDS) is a virtual data space leveraging existing standards and technologies, as well as governance models well-accepted in the data economy, to facilitate secure and standardized data exchange and data linkage in a trusted business ecosystem.
 It thereby provides a basis for creating smart-service scenarios and facilitating innovative cross-company businessprocesses, while at the same time guaranteeing data sovereignty for data owners.
 
-## Actors
+## Components
 
-The actors involved in the scenario are:
+The TRUE Connector is composed by:
 
--   **ECC**, representing the connector exchanging data
--   **Data app**, it is in charge of processing incoming request and provided the relative responses
--   **Usage control data app**, it will check if who are requesting the data has the grants to use that in a well defined policy
+-   **Execution core container (ECC)**, representing the connector exchanging data.
+-   **Fiware data app**, it is in charge of processing incoming request and provided the relative responses.
+-   **Usage Control data app (UC)**, it will check if who are requesting the data has the grants to use that in a well defined policy.
+	(The Fiware TRUE Connector integrates the [Fraunhofer MyData Framework](https://www.mydata-control.de/) for implementing the Usage Control. Details about the PMP and PEP components can be found [here](usage_control_rules.md))
 
+![TRUE Connector Architecture](img/TRUE_Connector_Architecture.png?raw=true "TRUE Connector Architecture")
+
+The connector can be run as consumer (send the request to the provider to obtain some data) or provider (provide the data to the consumers if allowed from the policies in UC).
+
+## Services
+
+### Supported Identity Providers
+An Identity Provider offers a service to create, maintain, manage, monitor, and validate identity information of and for participants.
+
+If it is needed to run the connector in developer mode please set the following properties as false:
+
+```
+CACHE_TOKEN=false
+FETCH_TOKEN_ON_STARTUP=false
+application.isEnabledDapsInteraction=false
+```
+
+This allow you to skip  the Daps interaction during the process in the development phase, otherwise you need to have a certificate provided from the CA offering Identity provider service.
+
+
+The TRUE Connector is able to interact with the following Identity Providers:
+
+* **AISECv1** put the certificate in the *cert* folder, edit related settings (i.e., *application.keyStoreName*, *application.keyStorePassword*) (in the *.env*) and set the *application.dapsVersion* (in the *resources/application-docker.properties*) to *v1*
+* **AISECv2** put the certificate in the *cert* folder,edit related settings (i.e., *application.keyStoreName*, *application.keyStorePassword*) (in the *.env*) and set the *application.dapsVersion* (in the *resources/application-docker.properties*) to *v2*
+* **ORBITER** put the certificate in the *cert* folder, edit related settings (i.e., *application.daps.orbiter.privateKey*, *application.daps.orbiter.password*) (in the *.env*) and set the *application.dapsVersion* (in the *resources/application-docker.properties*) to *orbiter*
+
+
+The *application.dapsUrl* (in the *resources/application-docker.properties*) property must be set properly in order to address the right DAPS server.
+
+### Clearing House
+The Clearing House is an intermediary that provides clearing and settlement services for all financial and data exchange transactions (logs all activities performed in the course of a data exchange).
+The Fiware TRUE Connector supports the communication with the ENG Clearing House for registering transactions, available as a service at:
+
+```
+CLEARING_HOUSE=http://109.232.32.193:8280/data
+```
+
+### Broker
+The Broker is an intermediary that stores and manages information about the data sources available.
+The Fiware TRUE Connector integrates some endpoints for interacting with an IDS Broker described in [Broker](https://github.com/Engineering-Research-and-Development/fiware-true-connector/blob/master/docs/broker.md) section
+
+## Flow
+
+The communication/message exchange starts from the data app level, that will expose APIs. Then the data app will forward the message to ECC that is in charge of enstablish a trusted communication with the other connector and services (CH, Broker, Identity Providers).
+Click [here](user_and_programmers_manual.md) for the manual explaining how to performe a test.

mkdocs.yml

@@ -1,7 +1,7 @@
 site_name: fiware TRUE Connector
-site_url: https://true-connector.readthedocs.org
+site_url: https://fiware-true-connector.readthedocs.io/en/latest/
 repo_url: https://github.com/Engineering-Research-and-Development/fiware-true-connector
-site_description: TRUE Connector Documentation
+site_description: Fiware TRUE Connector Documentation
 docs_dir: docs
 site_dir: html
 markdown_extensions: [toc, fenced_code]
@@ -12,7 +12,7 @@ extra_css:
     "https://www.fiware.org/style/fiware_readthedocs.css",
     "https://www.fiware.org/style/fiware_readthedocs_iot.css",
   ]
-google_analytics: ["UA-118589264-1", "true-connector.readthedocs.io"]
+google_analytics: ["UA-198735649-1", "fiware-true-connector.readthedocs.io"]
 pages:
   - "Home - Getting Started": "index.md"
   - "Quick Start Guide": "quick_start_guide.md"