Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update doc and step descriptions #9

Merged
merged 14 commits into from
Jan 9, 2024
Merged

Update doc and step descriptions #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
c1f1ff1
Update step descriptions
dwendland Oct 31, 2023
dd5c13e
Create doc sub-folder and move figures
dwendland Dec 20, 2023
79f89e9
Move contract management to doc folder
dwendland Dec 20, 2023
d2f8579
Initial version of detailed M2M flow description
dwendland Dec 22, 2023
1f4dafc
Adding VP token content example. Adding Server-side OpenID config end…
dwendland Dec 28, 2023
6a5f075
Finalize M2M description
dwendland Dec 29, 2023
dfcc6a1
Add sentence about PDP
dwendland Dec 29, 2023
d322e0c
Add sentence about VCVerifier access tokens
dwendland Dec 29, 2023
9a31560
Extend sentence about PDP
dwendland Dec 29, 2023
b98a125
Merge branch 'main' into update-doc
dwendland Dec 29, 2023
71198c8
Update contract management doc
dwendland Dec 29, 2023
87320f2
Update TOC
dwendland Jan 2, 2024
0958c66
Fix path to examples
dwendland Jan 2, 2024
bd636ab
Fix paths
dwendland Jan 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 17 additions & 72 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ FIWARE-Ops [data-space-connector repository](https://github.com/FIWARE-Ops/data-
- [Service interaction (M2M)](#service-interaction-m2m)
- [Implementation](#implementation)
- [Examples](#examples)
- [Contract Management via TMForum APIs](#contract-management-via-tmforum-apis)
- [Contract Management via TMForum APIs](#contract-management-via-tmforum-apis)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Expand Down Expand Up @@ -74,7 +74,7 @@ Thus, being provided as Helm chart, the FIWARE Data Space Connector can be deplo
The following diagram shows a logical overview of the different components of the FIWARE Data Space
Connector.

![connector-components](img/Connector_Components.png)
![connector-components](doc/img/Connector_Components.png)

Precisely, the connector bundles the following components:

Expand Down Expand Up @@ -117,7 +117,7 @@ self description.

The following displays the different steps during the onboarding.

![flows-onboarding](img/Flows_Onboarding.png)
![flows-onboarding](doc/img/Flows_Onboarding.png)

**Steps**

Expand Down Expand Up @@ -159,7 +159,7 @@ representing a buyer of products in the provider's connector.

The following displays the different steps for the consumer registration.

![flows-consumer-registration](img/Flows_Consumer-Registration.png)
![flows-consumer-registration](doc/img/Flows_Consumer-Registration.png)

**Steps**

Expand All @@ -169,12 +169,12 @@ The following displays the different steps for the consumer registration.
* The Verifier will request from the user’s wallet a VC that acredits him/her as LEAR of the organization,
eventually other VCs (steps 4-5). The wallet will check whether the verifier belongs to a participant in the
data space (step 6) and return the requested VCs (step 7)
* The Verifier checks whether the LEAR’s VC was issued by a trusted participant of the data space (step 8),
and also checks whether other VCs required were issued by trusted issuers (step 9)
* If verifications were ok, it issues a token (step 10) that is transmitted to the user (step 11)
* The Verifier checks whether the LEAR’s VC was issued by a trusted participant of the data space (steps 8-9),
and also checks whether other VCs required were issued by trusted issuers (step 10)
* If verifications were ok, it issues a token (step 11) that is transmitted to the user (step 12)
* Using the returned token, the user invokes [TM Forum API](https://www.tmforum.org/oda/open-apis/) to register
the consumer organization at the Connector
(steps 12-17) establishing the necessary access control (steps 12-14)
(steps 13-17) establishing the necessary access control (steps 13-14)
* Once the organization is registered and fulfills all the necessary information (which may take some time),
the organization is registered in the local trusted issuers list as trusted issuer of VCs which include claims
as buyer of products in the connector (step 18)
Expand All @@ -188,7 +188,7 @@ procure access to a specific service linked to a product of the provider.

The following displays the different steps for the contract negotiation.

![flows-contract-management](img/Flows_Contract-Management.png)
![flows-contract-management](doc/img/Flows_Contract-Management.png)

**Steps**

Expand Down Expand Up @@ -227,7 +227,7 @@ The following displays the different steps for the two different types of intera

#### Service interaction (H2M)

![flows-interaction-h2m](img/Flows_Interaction-H2M.png)
![flows-interaction-h2m](doc/img/Flows_Interaction-H2M.png)

**Steps**

Expand All @@ -254,7 +254,7 @@ The following displays the different steps for the two different types of intera

#### Service interaction (M2M)

![flows-interaction-h2m](img/Flows_Interaction-M2M.png)
![flows-interaction-h2m](doc/img/Flows_Interaction-M2M.png)

**Steps**

Expand All @@ -276,6 +276,9 @@ The following displays the different steps for the two different types of intera
extracted from the token is authorized to perform the given request (steps 10-12)
* If authorization is ok, the request is forwarded (step 13) and a response returned to the app (step 14)

A detailed description of the steps to be performed by client applications and service providers can be found
in the [Service Interaction (M2M)](./doc/flows/service-interaction-m2m) documentation.



## Implementation
Expand All @@ -296,66 +299,8 @@ which also provides instructions for the deployment.



#### Contract Management via TMForum APIs

With the [tmforum-api](https://github.com/FIWARE/tmforum-api) and the
[contract-management](https://github.com/FIWARE/contract-management) notification listener, the FIWARE
Data Space Connector provides components to perform contract management based on the TMForum APIs.

Via the TMForum APIs, providers can create product specifications and offerings. Consumer organisations
can register as a party and place product orders. In the case of a product order, the TMForum APIs will
send a notification to the contract-management notification listener, which will create an entry at the
Trusted Issuers List for the consumer organisation. Also compare to the flow descriptions
of [Consumer registration](#consumer-registration) and [Contract management](#contract-management).


### Authorization and authentication

The current implementation of the FIWARE Data Space Connector uses the decentralised version of the [i4Trust framework](https://i4trust.github.io/building-blocks/docs/i4Trust-BuildingBlocks_v4.0_UnderReview.pdf) with addtional support for http-path based decisions. This required, since the FIWARE Data Space Connector provides the [TMForum APIs](https://github.com/FIWARE/tmforum-api), instead of NGSI-LD APIs.

> :construction: A more powerful security framework, also supporting attribute-based policies for the TMForum API, is currently build on top of the existing framework within the [DOME Marketplace Project](https://dome-marketplace.eu/).

#### Roles

The [example-instance](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/dsba/packet-delivery/data-space-connector) of the Data Space Connector supports two roles:

* the ```PROVIDER```, which is able to create Product Specifications and Offerings on the TMForum-API
* the ```CONSUMER```, which is able to order products through the api.
* the ```LEGAL_REPRESENTATIVE```, which is able to register an organization through the Parties API.

The roles are connected to policies inside the [Authorization Registry](https://github.com/FIWARE-Ops/data-space-connector/tree/main/applications/keyrock). Those policies define the paths and operations available for each role at the TMForum API. In this case its:

PROVIDER: "GET","POST","PUT","DELETE" on all deployed TMForum APIs
CONSUMER: "GET" on the ProductCatalogManagement-API and "GET","POST","PUT" on the ProductOrderingManagement-API
LEGAL_REPRESENTATIVE: "GET", "POST" and "PUT" on the Parties-API

#### Credentials and Role-Assingment

The VerifiableCredentials containing the ```PROVIDER```,```CONSUMER``` and ```LEGAL_REPRESENTATIVE``` roles are issued through the standard mechanisms of the framework, e.g. by each individual participant. The example-instance of the Data Space Connector is in the role of an ```PROVIDER```. Therefore, the user ```standard-employee```(see the [documentation](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/dsba#credentials) for credentials) can request a ```NaturalPersonCredential``` at [PacketDeliveries Keycloak](https://packetdelivery-kc.dsba.fiware.dev/realms/fiware-server/account/#/) with a compliant wallet (as of now, the [demo-wallet.fiware.dev](https://demo-wallet.fiware.dev) can be used).

For the Consumer-Participant, two users are provided:
- the ```legal-representative```(see the [documentation](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/dsba#credentials)) with the role ```LEGAL_REPRESENTATIVE```
- the ```standard-user```(see the [documentation](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/dsba#credentials)) with the role ```CONSUMER```
In order to get the credentials, use the [HappyPets Keycloak](https://happypets-kc.dsba.fiware.dev/realms/fiware-server/account/#/).

> :bulb: The framework would allow users that have both roles already. We decided to split them in order to have a clear flow.

#### Example flow

> :construction: The [Business API Ecosystem](https://github.com/FIWARE-TMForum/Business-API-Ecosystem) as a Marketplace solution build on top of the TMForum-APIs is currently beeing updated to the latest TMForum-APIs and the security framework. Once its finished, it can be used a Marketplace, including UI, for the Data Space Connector.


To provide a working example for Contract Management, using the Data Space Connector, a [postman colletion is provided](./examples/tmf/).
It includes the following steps of the aquisition process:

> :bulb: Since frontend-solutions are still under construction, plain REST-calls are used for the flow. Since all calls require a valid JWT, the [demo-portal](https://packetdelivery-portal.dsba.fiware.dev/) for the provider has a link to get a plain token in exchange for the Verifiable Credential. Log-in either as CONSUMER or PROVIDER(see [Credentials and Role-Assignemnt](#credentials-and-role-assingment)) to get tokens.

0. In order to have the consumer registered, it has to be created as an ```Organization``` through the [TMForum Party-API](https://github.com/FIWARE/tmforum-api/tree/main/party-catalog). The registration needs to happen with a direct api-call to the Parties-API, with a token in Role ```LEGAL_REPRESENTATIVE```: [POST /organization](./examples/tmf/tmf.postman_collection.json#l80)

1. Creating an offer as the PROVIDER (use a JWT retrieved for user ```standard-employee``` of [PacketDelivery](https://packetdelivery-kc.dsba.fiware.dev/realms/fiware-server/account/#/)):
1. Create the product specification
2. Create the product offering
### Contract Management via TMForum APIs

2. Create a product order (e.g. buy the product) as the CONSUMER (use a JWT retrieved for user ```standard-user``` of [HappyPets](https://happypets-kc.dsba.fiware.dev/realms/fiware-server/account/#/))
A detailed description of the contract management via TMForum APIs can be found in
the [Contract Management](./doc/flows/contract-management) documentation.

After the product was ordered, a notfication will be triggered towards the [Contract Management Service](https://github.com/FIWARE/contract-management). The service will use the information provided as part of the notification, to add the ```CONSUMER``` Organization as a Trusted Issuer to the [Trusted Issuers List](https://github.com/FIWARE/trusted-issuers-list) of PacketDelivery and therefore allow Happy Pets (as the ```CONSUMER``` Organization) issue credentials to its customers to access Packet Deliveries (e.g. the ```PROVIDER```) Services(see [description of Service Usage in the -Data Space](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/#service-usage)).
65 changes: 65 additions & 0 deletions doc/flows/contract-management/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Contract Management

With the [tmforum-api](https://github.com/FIWARE/tmforum-api) and the
[contract-management](https://github.com/FIWARE/contract-management) notification listener, the FIWARE
Data Space Connector provides components to perform contract management based on the TMForum APIs.

Via the TMForum APIs, providers can create product specifications and offerings. Consumer organisations
can register as a party and place product orders. In the case of a product order, the TMForum APIs will
send a notification to the contract-management notification listener, which will create an entry at the
Trusted Issuers List for the consumer organisation. Also compare to the flow descriptions
of [Consumer registration](#consumer-registration) and [Contract management](#contract-management).


## Authorization and authentication

The current implementation of the FIWARE Data Space Connector uses the decentralised version of the [i4Trust framework](https://i4trust.github.io/building-blocks/docs/i4Trust-BuildingBlocks_v4.0_UnderReview.pdf) with addtional support for http-path based decisions. This required, since the FIWARE Data Space Connector provides the [TMForum APIs](https://github.com/FIWARE/tmforum-api), instead of NGSI-LD APIs.

> :construction: A more powerful security framework, also supporting attribute-based policies for the TMForum API, is currently build on top of the existing framework within the [DOME Marketplace Project](https://dome-marketplace.eu/).

### Roles

The [example-instance](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/dsba/packet-delivery/data-space-connector) of the Data Space Connector supports two roles:

* the ```PROVIDER```, which is able to create Product Specifications and Offerings on the TMForum-API
* the ```CONSUMER```, which is able to order products through the api.
* the ```LEGAL_REPRESENTATIVE```, which is able to register an organization through the Parties API.

The roles are connected to policies inside the [Authorization Registry](https://github.com/FIWARE-Ops/data-space-connector/tree/main/applications/keyrock). Those policies define the paths and operations available for each role at the TMForum API. In this case its:

PROVIDER: "GET","POST","PUT","DELETE" on all deployed TMForum APIs
CONSUMER: "GET" on the ProductCatalogManagement-API and "GET","POST","PUT" on the ProductOrderingManagement-API
LEGAL_REPRESENTATIVE: "GET", "POST" and "PUT" on the Parties-API

### Credentials and Role-Assignment

The VerifiableCredentials containing the ```PROVIDER```,```CONSUMER``` and ```LEGAL_REPRESENTATIVE``` roles are issued through the standard mechanisms of the framework, e.g. by each individual participant. The example-instance of the Data Space Connector is in the role of an ```PROVIDER```. Therefore, the user ```standard-employee```(see the [documentation](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/dsba#credentials) for credentials) can request a ```NaturalPersonCredential``` at [PacketDeliveries Keycloak](https://packetdelivery-kc.dsba.fiware.dev/realms/fiware-server/account/#/) with a compliant wallet (as of now, the [demo-wallet.fiware.dev](https://demo-wallet.fiware.dev) can be used).

For the Consumer-Participant, two users are provided:
- the ```legal-representative```(see the [documentation](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/dsba#credentials)) with the role ```LEGAL_REPRESENTATIVE```
- the ```standard-user```(see the [documentation](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/dsba#credentials)) with the role ```CONSUMER```
In order to get the credentials, use the [HappyPets Keycloak](https://happypets-kc.dsba.fiware.dev/realms/fiware-server/account/#/).

> :bulb: The framework would allow users that have both roles already. We decided to split them in order to have a clear flow.

### Example flow

> :construction: The [Business API Ecosystem](https://github.com/FIWARE-TMForum/Business-API-Ecosystem) as a Marketplace solution build on top of the TMForum-APIs is currently beeing updated to the latest TMForum-APIs and the security framework. Once its finished, it can be used a Marketplace, including UI, for the Data Space Connector.


To provide a working example for Contract Management, using the Data Space Connector, a [postman colletion is provided](../../../examples/tmf/).
It includes the following steps of the aquisition process:

> :bulb: Since frontend-solutions are still under construction, plain REST-calls are used for the flow. Since all calls require a valid JWT, the [demo-portal](https://packetdelivery-portal.dsba.fiware.dev/) for the provider has a link to get a plain token in exchange for the Verifiable Credential. Log-in either as CONSUMER or PROVIDER (see [Credentials and Role-Assignment](#credentials-and-role-assignment)) to get tokens.

0. In order to have the consumer registered, it has to be created as an ```Organization``` through the [TMForum Party-API](https://github.com/FIWARE/tmforum-api/tree/main/party-catalog). The registration needs to happen with a direct api-call to the Parties-API, with a token in Role ```LEGAL_REPRESENTATIVE```: [POST /organization](../../../examples/tmf/tmf.postman_collection.json#l80)

1. Creating an offer as the PROVIDER (use a JWT retrieved for user ```standard-employee``` of [PacketDelivery](https://packetdelivery-kc.dsba.fiware.dev/realms/fiware-server/account/#/)):
1. Create the product specification
2. Create the product offering

2. Create a product order (e.g. buy the product) as the CONSUMER (use a JWT retrieved for user ```standard-user``` of [HappyPets](https://happypets-kc.dsba.fiware.dev/realms/fiware-server/account/#/))

After the product was ordered, a notfication will be triggered towards the [Contract Management Service](https://github.com/FIWARE/contract-management). The service will use the information provided as part of the notification, to add the ```CONSUMER``` Organization as a Trusted Issuer to the [Trusted Issuers List](https://github.com/FIWARE/trusted-issuers-list) of PacketDelivery and therefore allow Happy Pets (as the ```CONSUMER``` Organization) to issue credentials to its customers to access Packet Deliveries (e.g. the ```PROVIDER```) Services (see [description of Service Usage in the Data Space](https://github.com/FIWARE-Ops/fiware-gitops/tree/master/aws/dsba#service-usage)).


Loading
Loading