diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a6bfa338..447c98873 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ New features, fixed bugs, known defects and other noteworthy changes to each release of the Catena-X Portal Assets. +## 1.6.0-RC4 + +### Change +- Documentation of registration and technical integration updated (removal of all daps related documentation) +- Added new notification types and messages inside the notification service documentation +- Enhanced policy documentation as part of the user documentation of connectors + ## 1.6.0-RC3 ### Change diff --git a/developer/02. Technical Integration/01. Connector Registration/01. Summary.md b/developer/02. Technical Integration/01. Connector Registration/01. Summary.md index a149eb5fa..1b6366e40 100644 --- a/developer/02. Technical Integration/01. Connector Registration/01. Summary.md +++ b/developer/02. Technical Integration/01. Connector Registration/01. Summary.md @@ -20,5 +20,6 @@ Connector stakeholders are mainly app providers and data provider (active CX par For the scenario "bring your own connector", the user will be able to register the connector by entering the relevant information. In the case of a "connector as a service" case, the relevant data fields need to get still defined by the Product Team CaaS (not in scope for release 1)

-image - +image +
+
diff --git a/developer/02. Technical Integration/01. Connector Registration/02. View Connector.md b/developer/02. Technical Integration/01. Connector Registration/02. View Connector.md index 5ff40b105..054c4d40e 100644 --- a/developer/02. Technical Integration/01. Connector Registration/02. View Connector.md +++ b/developer/02. Technical Integration/01. Connector Registration/02. View Connector.md @@ -3,7 +3,7 @@

-image +image


@@ -61,7 +61,33 @@ The user can retrieve all connectors which are connected to his/her company as c ! GET /api/administration/connectors ``` -Endpoints supports pagination + +
+ +Response Body + + { + "meta": { + "totalElements": 0, + "totalPages": 0, + "page": 0, + "contentSize": 0 + }, + "content": [ + { + "name": "string", + "location": "string", + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "type": "COMPANY_CONNECTOR", + "status": "PENDING", + "hostId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "hostCompanyName": "string", + "selfDescriptionDocumentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "documentName": "string" + } + ] + } +

@@ -93,22 +119,35 @@ Same as the "Onboarded Connector" section, connector status and details will be Response Body { + "meta": { + "totalElements": 0, + "totalPages": 0, + "page": 0, + "contentSize": 0 + }, + "content": [ + { "name": "string", "location": "string", - "id": "uuid", - "type": "e.g. CONNECTOR_AS_A_SERVICE", - "status": "e.g. PENDING", - "dapsRegistrationSuccessful": true, - "providerCompanyName": "string", - "selfDescriptionDocumentId": "uuid" + "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "type": "COMPANY_CONNECTOR", + "status": "PENDING", + "hostId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "hostCompanyName": "string", + "selfDescriptionDocumentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "documentName": "string" + } + ] } +
+

Data Mapping -image +image

diff --git a/developer/02. Technical Integration/01. Connector Registration/03. Create new Connector Registration.md b/developer/02. Technical Integration/01. Connector Registration/03. Create new Connector Registration.md index 15fda6d5b..695f5b3db 100644 --- a/developer/02. Technical Integration/01. Connector Registration/03. Create new Connector Registration.md +++ b/developer/02. Technical Integration/01. Connector Registration/03. Create new Connector Registration.md @@ -1,59 +1,20 @@ ## 1. Create new Connector Registration - self-owned
-image +image

The user can create a new connector registration by using the connector POST call.
The registration will automatically -* register the connector in the daps authentication service (with the public key uploaded inside the connector registration UI / endpoint) * trigger the SD Factory to create the self-description of the connector
-
- -#### Details to the DAPS - -The connector registration job triggers the daps component to register the respective connector inside the daps. -Therefore the portal backend transforms the connector registration data and provides the needed information to the daps registration service. -Inside daps, the client for the respective connector is getting created and success message is getting responded back to the portal. - -DAPS is not directly reachable. Due to security regulations, the DAPS registration service is wrapped by the portal endpoint. -##### API Details - -```diff -! POST /daps -``` +If connector data have been successfully stored and SD is created and stored; the connector record will receive the status "ACTIVE".
- -Request Body - -```json -{ - "clientName":"string", - "securityProfile":"BASE_SECURITY_PROFILE", - "referringConnector": "connector.url+BPN (own connector: own bpn; managed connector: bpn of the provider)", - "file": "string($binary)" - } -``` - -Details - -* clientName: Name of a client we create a record for -* securityProfile: Default value is idsc:BASE_SECURITY_PROFILE -* referringConnector: URL of a connector with BPN at the end (see details above) -* file: Certificate of a Connector in PEM format - -
- -
- -With the success response from DAPS, the newly created DAPS clientID is getting provided back to the portal inside the response body. The portal stores the clientID inside the portal db to be able to trigger (if needed) the connector change or deletion in a later stage. -
#### Details to the SD @@ -101,21 +62,14 @@ Execution: In case of status "success" * content is stored as json file inside the portal db * connector status: - * Active - if the daps auth has status "true" set the connector status to "ACTIVE" - * Pending - if the connector.daps_registration_successful is "false" and connector.self_description_document_id is != NULL - * Pending - if the connector.daps_registration_successful is "false" and connector.self_description_document_id is = NULL - * Pending - if the connector.daps_registration_successful is "true" and connector.self_description_document_id is = NULL + * Active - if the sd_document_id is != NULL set the connector status to "ACTIVE" + * Pending - if the sd_document_id is = NULL
In case of status "fail" * set status of the "Self_Description_SO" to "FAILED" and store the message inside the checklist comment field application_checklist.comment -
- -Technical explanation: if the connector.daps_registration_successful is "true" and connector.self_description_document_id is != NULL; connector status is "ACTIVE" - -

@@ -175,16 +129,19 @@ Request Body ## 2. Create new Connector Registration - managed +image + +
+
+ Service Provider can create a new registration for a company which subscribed for a service provider service Same as for self-owned connectors, the connector registration will automatically -* register the connector in the daps authentication service (with the public key uploaded inside the connector registration UI / endpoint) * trigger the SD Factory to create the self-description of the connector
-If connector data have been successfully stored; DAPS auth has been successful and SD is created and stored; the connector record will receive the status "ACTIVE". -Technical explanation: if the connector.daps_registration_successful is "true" and connector.self_description_document_id is != NULL; connector status is "ACTIVE" +If connector data have been successfully stored and SD is created and stored; the connector record will receive the status "ACTIVE".

diff --git a/developer/02. Technical Integration/01. Connector Registration/04. DAPS Registration.md b/developer/02. Technical Integration/01. Connector Registration/04. DAPS Registration.md deleted file mode 100644 index b68adbe1e..000000000 --- a/developer/02. Technical Integration/01. Connector Registration/04. DAPS Registration.md +++ /dev/null @@ -1,36 +0,0 @@ -## 4 Retrigger DAPS - -In case the DAPS registration failed as part of the connector registration, the user will be able to retrigger the endpoint directly. -For this endpoint; following data will be pushed - -
-
- -image -
-
- ->Validation: -> ->* connectorId existing ->* validate is daps registration flag is false (if not, dont run the daps registration) ->* if the endpoint gets an error => send the error back to the front-end and keep the connector daps registration flag on "false" ->* if the endpoint result is "success" => set the connector daps registration flag to "true" and send success message to the FE -
-
- -#### API Details - -```diff -! POST /api/administration/connectors/trigger-daps/{connectorId} -``` - -
- -Request Body: - - file (certificate) - - -
-
diff --git a/developer/02. Technical Integration/01. Connector Registration/06. Delete Connector.md b/developer/02. Technical Integration/01. Connector Registration/06. Delete Connector.md index 42372cbbe..31bebfd5e 100644 --- a/developer/02. Technical Integration/01. Connector Registration/06. Delete Connector.md +++ b/developer/02. Technical Integration/01. Connector Registration/06. Delete Connector.md @@ -8,11 +8,6 @@ Delete own connector. The deletion will disable the discovery service for the co image

-
- -> **Note** -> In the current implementation; the deactivation of the SD document as well as the deletion of the DAPS Auth is not yet included -

@@ -32,3 +27,7 @@ Request Body

+With the deletion, the SD document is set to "DELETED" and the connector retrieves the status "INACTIVE". + +
+
diff --git a/developer/Technical Documentation/Interface Contracts/BPDM.md b/developer/Technical Documentation/Interface Contracts/BPDM.md index 164811071..c68fa8889 100644 --- a/developer/Technical Documentation/Interface Contracts/BPDM.md +++ b/developer/Technical Documentation/Interface Contracts/BPDM.md @@ -8,19 +8,15 @@ BPDM Data Pool provides an API (Reference Data API) to lookup business partner d API authentication is managed by API keys which is processed via HTTP header. This key manages also authorization, e.g., access to the CX data pool (instead of other community data).

-For the registration process we are using the BPDM data call to pull the company basic data. -
-2 Options are available for the data pull -
-* Via Company Name (Level 2 - not yet implemented) -* Via BPN Number (BPN Generator: BPN Generator: Modes of Operation) +For the registration process we are using the BPDM data call to pull the company basic data based on a BPNL data input.

## Architecture Overview To integrate the API into CX onboarding process, portal team just have to call the lookup REST endpoint and transform the response into a pick list for the portal user.
-image +
+image

@@ -43,8 +39,20 @@ Retrieving company data from the CX mirror. ```
- idValue: {BPN-Number}, - idType: BPN + +Request Body +
+ + idValue: {BPN-Number}, + idType: BPN + +
+
+ +The mentioned endpoint is provided by the registration service. +Behind that, the BPDM endpoint {BPDM Host}/pool/api/catena/legal-entities/{idValue} is getting called. +The portal is using an technical user for the authentication. The technical user bearer token is send via the api rest call to bpdm. +

@@ -64,10 +72,5 @@ Retrieving company data from the CX mirror.

-### Service Call via CompanyName -
-currently not supported -
-
diff --git a/developer/Technical Documentation/Others/Notifications.md b/developer/Technical Documentation/Others/Notifications.md index 8c1f90421..24ef51772 100644 --- a/developer/Technical Documentation/Others/Notifications.md +++ b/developer/Technical Documentation/Others/Notifications.md @@ -281,11 +281,27 @@ Welcome Messages, triggered by the api endpoint Topic | Notification Type | Content | UI Message | Receiver -------- | -------- | -------- | -------- | -------- -INFO | WELCOME | n/a | Triggered from the FE locales file
Welcome to the Catena-X Network. To easily get you onboarded, a number of notifications / onboarding steps have been defined. Please check your notifications and start the configuration of your company area inside the portal to have a network experience based on your need. | New Registered Company Admin -INFO | WELCOME_USE_CASES | n/a | Triggered from the FE locales file
The network is quite huge, we want to ensure that you can focus on your preferred use cases. Select your preferred use case from the table below. | New Registered Company Admin -INFO | WELCOME_SERVICE_PROVIDER | n/a | Triggered from the FE locales file
If you need a service provider to help you with setting up your dataspace or an EDC, just follow us to the Service Provider Marketplace LINK | New Registered Company Admin -INFO | WELCOME_CONNECTOR_REGISTRATION | n/a | Triggered from the FE locales file
You do not have any registered Connector so far – have a look at the connector offers and get your connector to participate. LINK | New Registered Company Admin -INFO | WELCOME_APP_MARKETPLACE | n/a | Triggered from the FE locales file
Get a first inside into available apps, just follow us to the marketplace for apps. LINK | New Registered Company Admin +INFO | WELCOME | n/a | Triggered from the FE locales file
Welcome to the Catena-X Network. To easily get you onboarded, a number of notifications / onboarding steps have been defined. Please check your notifications and start the configuration of your company area inside the portal to have a network experience based on your need. | New Registered Company Admin +INFO | WELCOME_USE_CASES | n/a | Triggered from the FE locales file
The network is quite huge, we want to ensure that you can focus on your preferred use cases. Select your preferred use case from the table below. | New Registered Company Admin +INFO | WELCOME_SERVICE_PROVIDER | n/a | Triggered from the FE locales file
If you need a service provider to help you with setting up your dataspace or an EDC, just follow us to the Service Provider Marketplace LINK | New Registered Company Admin +INFO | WELCOME_CONNECTOR_REGISTRATION | n/a | Triggered from the FE locales file
You do not have any registered Connector so far – have a look at the connector offers and get your connector to participate. LINK | New Registered Company Admin +INFO | WELCOME_APP_MARKETPLACE | n/a | Triggered from the FE locales file
Get a first inside into available apps, just follow us to the marketplace for apps. LINK | New Registered Company Admin + +
+
+ +#### Manage your company details +Company detail change messages, triggered by the api endpoint + +* PUT /api/administration/companydata/credentials/{credentialId}/approval +* PUT /api/administration/companydata/credentials/{credentialId}/reject + +
+ +Topic | Notification Type | Content | UI Message | Receiver +-------- | -------- | -------- | -------- | -------- +INFO | CREDENTIAL_APPROVAL | {"type":"{company_ssi_details.type}",
"credentialId":"{company_ssi_details.id}" | Triggered from the FE locales file
"Verified Credential {credentialType} assigned
Verified Credential {credentialType} got assigned to your company wallet." | VC Requester +INFO | CREDENTIAL_REJECT | {"type":"{company_ssi_details.type}",
"credentialId":"{company_ssi_details.id}" | Triggered from the FE locales file
"Verified Credential {credentialType} declined
Verified Credential {credentialType} got declined. You can start a new request immediately." | VC Requester

@@ -306,6 +322,22 @@ OFFER | SERVICE_RELEASE_REQUEST | OfferId: {offer.id}
RequestorCompanyName:{c

+#### Offer Change Process +Offer Change Messages, triggered by the api endpoint + +* POST /api/apps/AppChange/{appId}/role/activeapp +* PUT /api/apps/AppChange/{appId}/subscription/{subscriptionId}/tenantUrl + +
+ +Topic | Notification Type | Content | UI Message | Receiver +-------- | -------- | -------- | -------- | -------- +INFO | SUBSCRIPTION_URL_UPDATE | {"appId":"{offer.id}",
"appName":"{offer.name}",
"oldUrl":"{app_subscription_details.url}"
"newUrl":"{app_subscription_details.url}" | Triggered from the FE locales file
"App URL {appName} updated
The app provider has changed the stored App Instance URL for your subscribed app {AppName}." | tbd +INFO | APP_ROLE_ADDED | not yet supported | not yet supported | not yet supported + +
+
+ #### Offer Subscription Offer Subscription Messages, triggered by the api endpoint diff --git a/docs/02. Technical Integration/01. Connector Registration/01. Connector Overview.md b/docs/02. Technical Integration/01. Connector Registration/01. Connector Overview.md index 9506c1d72..aaa492834 100644 --- a/docs/02. Technical Integration/01. Connector Registration/01. Connector Overview.md +++ b/docs/02. Technical Integration/01. Connector Registration/01. Connector Overview.md @@ -7,17 +7,11 @@ Additionally the user can register easily new connectors.

-image +image



-#### DAPS Auth Status - -
-image -
- #### SelfDescription Status
@@ -41,6 +35,6 @@ Same as the "Onboarded Connector" section, connector status and details will be

-image +image


diff --git a/docs/02. Technical Integration/01. Connector Registration/02. Connector Registration.md b/docs/02. Technical Integration/01. Connector Registration/02. Connector Registration.md index 7a8b35726..02b2f51f5 100644 --- a/docs/02. Technical Integration/01. Connector Registration/02. Connector Registration.md +++ b/docs/02. Technical Integration/01. Connector Registration/02. Connector Registration.md @@ -20,7 +20,7 @@ Click "Next" and enter the following data:

-image +image


@@ -28,11 +28,11 @@ Click "Confirm" as soon as all data are added.
-The connector registration will automatically trigger the daps certificate via the public key which was uploaded by the user. Same applies for the Self-Description of the connector. +The connector registration will automatically trigger the Self-Description creation of the connector.
-In case the DAPS is failing, the connector will still get registered and DAPS registration will be hold on "PENDING". In the scenario of an PENDING connector; the user will be enabled to retrigger the missing service registration (in this case DAPS) to enable the usage of the connector inside the network fully. +The connector will stay in status "PENDING" as long as the seld-description creation is ongoing. Usually the process takes around 1 minute.

@@ -71,7 +71,7 @@ Click "Next" and enter the following data:

-image +image


@@ -79,7 +79,7 @@ Click "Confirm" as soon as all data are added.
-The connector registration will automatically trigger the daps certificate via the public key which was uploaded by the user. Same applies for the Self-Description of the connector. +The connector will stay in status "PENDING" as long as the seld-description creation is ongoing. Usually the process takes around 1 minute.

diff --git a/docs/02. Technical Integration/01. Connector Registration/03. DAPS Registration.md b/docs/02. Technical Integration/01. Connector Registration/03. DAPS Registration.md deleted file mode 100644 index f82ef7e9f..000000000 --- a/docs/02. Technical Integration/01. Connector Registration/03. DAPS Registration.md +++ /dev/null @@ -1,16 +0,0 @@ -## 4 DAPS Registration - -In the normal connector registration flow; the daps registration is automatically triggered/executed. -In case the DAPS registration failed (visible in the connector overview via greyed out lock icon), the user will be able to retrigger the endpoint directly. -To retrigger daps; click on the grey lock icon to open up the overlay where the public key of the token can get uploaded. -
-
-

-image -

-
-
- -As soon as the user clicks confirm; the icon on the connector overview will get green and the daps auth is successfully configured for your connector. -
-
diff --git a/docs/02. Technical Integration/01. Connector Registration/06. OpenAPI.md b/docs/02. Technical Integration/01. Connector Registration/06. OpenAPI.md index f72844fd2..d5915423a 100644 --- a/docs/02. Technical Integration/01. Connector Registration/06. OpenAPI.md +++ b/docs/02. Technical Integration/01. Connector Registration/06. OpenAPI.md @@ -12,12 +12,11 @@ Service Provider can create a new registration for a company which subscribed fo Same as for self-owned connectors, the connector registration will automatically -* register the connector in the daps authentication service (with the public key uploaded inside the connector registration UI / endpoint) * trigger the SD Factory to create the self-description of the connector
-If connector data have been successfully stored; DAPS auth has been successful and SD is created and stored; the connector record will receive the status "ACTIVE". Technical explanation: if the connector.daps_registration_successful is "true" and connector.self_description_document_id is != NULL; connector status is "ACTIVE" +If connector data have been successfully stored; the connector record will receive the status "ACTIVE".

diff --git a/docs/02. Technical Integration/01. Connector Registration/07. FAQ.md b/docs/02. Technical Integration/01. Connector Registration/07. FAQ.md index 3f36bece4..ab88089af 100644 --- a/docs/02. Technical Integration/01. Connector Registration/07. FAQ.md +++ b/docs/02. Technical Integration/01. Connector Registration/07. FAQ.md @@ -6,7 +6,7 @@ A connector can get created via the user navigation "Connector Registration". The sub-menu is only available for company administrators.

-The connector registration will auto generate the connector self-description and the daps authentication. +The connector registration will auto generate the connector self-description.

image @@ -37,111 +37,16 @@ The deletion of a connector is similar as the registration only possible if the To delete a connector registered inside the network, get to the connector overview and trigger the deletion via the delete icon.
image
-With the successful deletion, the daps registration will get disabled and the connector wont be available in the dataspace anymore. +With the successful deletion, the connector is getting removed from the edc discovery service.

### Why is my connector "PENDING"? -A pending connector status shows, that the connector is not fully registered inside the dataspace yet. For example: the daps authentication might be missing or the connector provider still needs to configure the connector before the connector is fully usable. +A pending connector status shows, that the connector is not fully registered inside the dataspace yet. In case of a managed connector - please contact for any questions your service provider.

-### Why is my connector authentication icon green or grey? -The connector authentication icon shows the authentication status. If the icon is grey, the authentication was unsuccessful; in this case a new authentication needs to get manually triggered. Otherwise the connector will be not useable inside the dataspace. -A green connector icon shows the active authentication registration. -
-
- - -### Whats a public key and how do I create the public key? -Self-Signed certificates (with the public key) are relevant to crate a secure authentication between my connector and the catena-x dataspace. -Therefore the own created public key needs to get created by the connector owner and shared with the CX dataspace authentication system. -
-To create the public key, please follow the steps defined below: -* Install OpenSSL or LibreSSL (509.X Zertifikat) -* Create the keys with the following data - * Make sure you have your BPN and Legal Entity data of the connector owner (not the host) available - * URL of the connector - -
- -#### Steps to install OpenSSL on mac with brew: - - ##### Step 1: Install brew - - * Open terminal on your Mac - * Enter the command: - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - * Reference link: https://brew.sh/ - - -
-image -
- - ##### Step 2: Add Homebrew to your path and install openssl - - Run these three commands in your terminal to add Homebrew to your PATH: - - * echo '# Set PATH, MANPATH, etc., for Homebrew.' >> /Users/ $USER/.zprofile - * echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/ $USER/.zprofile - * eval "$(/opt/homebrew/bin/brew shellenv)" - - - Then run brew update and install: - * brew update - * brew install openssl - -
-image -
- - ##### Step 3: Navigate to the folder having openssl.cnf and run the command - -
-image - -
-
- -#### Steps to install OpenSSL on windows: - - ##### Step 1: - Install OpenSSL. For example using Cygwin client. https://www.cygwin.com/install.html. - Select setup-x86_64.exe file and download it. - -
-image -
- -During installation you can select some options or you can leave it all as default. - - ##### Step 2: - When installation is done, launch Cygwin and use instruction below for creating self-sign certificate. Do not forget that you need to download and place openssl.cnf file in directory where you want to run openssl command. - -With that, you are all set. - -
-
- -The attached openssl.cnf shall be used as a configuration file for openssl in order to generate correct certificate. The certificate shall include SKI and AKI extensions. - -Assuming the openssl.cnf is located in current directory a requestor shall execute this code and answer the questions the tool asks: - -openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -text -keyout private.key -out certificate.crt -config openssl.cnf - -
-
- -[openssl.txt](https://github.com/catenax-ng/tx-portal-assets/files/10862803/openssl.txt) -(please download the file and store it as cnf file before using it) - -
-
- -Here private.key is the private key and certificate.crt is a certificate you should use for the registration. These files are generated by the tool and are placed to the directory where you run oppenssl from. - Please use the Portal to register your Connectors. The connector shall be configured to use generated keys, the DAPS server shall be set to the https://daps.beta.demo.catena-x.net diff --git a/docs/02. Technical Integration/01. Connector Registration/08. Policy Management.md b/docs/02. Technical Integration/01. Connector Registration/08. Policy Management.md index d9c18bf97..6f3314c53 100644 --- a/docs/02. Technical Integration/01. Connector Registration/08. Policy Management.md +++ b/docs/02. Technical Integration/01. Connector Registration/08. Policy Management.md @@ -1,8 +1,189 @@ -# Policy Management +## Policy Management + +### Overview + +Policies are used to define data access policies as well as usage details. + +Access means it defined who can view data offers. Usage defines the data access itself - means contract negotiations and data consumption. E.g. Company A can see that Company B has a Data Offer of last week produced vehicle data - however due to missing usage rights the company can not accept the agreement/data offer and can't access those data. + +
+ +* [Example: "Public Policy"](#example-public-policy) +* [Example: "Membership Policy"](#example-membership-policy) +* [Example: Combined Policy for "Membership Policy" & "BPN Policy"](#example-combined-policy-for-membership-policy--bpn-policy) +* [Example: Combined Policy for "Membership Policy" & Usage: "Traceability Credential"](#example-combined-policy-for-membership-policy--usage-traceabiliy-credential) +* [Additional specific examples](#further-specific-examples) + +
+
+ +### Setup Access & Usage Policies + +#### Example: "Public Policy" + +A public policy is a policy which allows everyone to access the data offer - example see below. Please note - the policy should not be used outside dev/int environments. + + { + "@id": "always-true", + "@type": "edc:PolicyDefinition", + "edc:createdAt": 1690454750566, + "edc:policy": { + "@id": "87e679c1-6a4e-42e0-90e2-021e2a171f8d", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:leftOperand": "ALWAYS_TRUE", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "true" + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + } + } + +
+
+ +#### Example: "Membership Policy" + +Membership policy - as defined below - allows only data consumers with the "CX Membership Credential" to view/access a data offer. + + { + "@id": "membership-required-policy", + "@type": "edc:PolicyDefinition", + "edc:createdAt": 1690884819803, + "edc:policy": { + "@id": "f8bbb24b-dfc9-4879-b7a5-8ac4ed30307b", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:leftOperand": "Membership", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, + "@context": {} + } + +
+
+ +#### Example: Combined Policy for "Membership Policy" & "BPN Policy" + +In the example below - the data consumer needs to have the "CX Membership Credential" as well as a specific defined BPN to be able to access the data offer + + { + "@id": "membership-required-with-bpn-policy", + "@type": "edc:PolicyDefinition", + "edc:createdAt": 1690457344107, + "edc:policy": { + "@id": "510615fa-1a8a-4ab6-9b80-5b38bfea2c55", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:and": [ + { + "odrl:leftOperand": "Membership", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + }, + { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "BPNL********" + } + ] + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, + "@context": {} + } + +
+
+ + +#### Example: Combined Policy for "Membership Policy" & Usage: "Traceability Credential" + +In the example below - the data consumer needs to have the "CX Membership Credential" to view the data offer (inside the catalog) and traceability to initiate the negotiation. + + { + "@id": "traceability-usage-policy", + "@type": "edc:PolicyDefinition", + "edc:createdAt": 1690457344107, + "edc:policy": { + "@id": "510615fa-1a8a-4ab6-9b80-5b38bfea2c55", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:and": [ + { + "odrl:leftOperand": "Membership", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + }, + { + "odrl:leftOperand": "FrameworkAgreement.traceability", // FrameworkAgreement.{credentialAttributeName} + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "active" + }, + { + "odrl:leftOperand": "PURPOSE", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "ID 3.1 Trace" + } + ] + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, + "@context": {} + } + +
+
-## Overview +--------- -For the following Scenarios, we assume there is a Partner 1 (provider) who wants to provide Data for Partner 2 (consumer). +
+
+ +### Further Specific Examples + +For the following Scenarios, we assume there is a Partner 1 (provider) who wants to provide Data for Partner 2 (consumer). Partner 1 (provider) has the Business-Partner-Number BPN12345. @@ -34,11 +215,12 @@ So for this example, if Partner 2 does a catalogue request to Partner 1, the fol "contractTemplates": "https://public.catena-x.org/contracts/" } } -### Scenario 1 + +#### Scenario 1 Partner 1 wants to create an Access Policy, that Partner 2 can only receive the Contract offer if its BPN matches AND if it has the Traceability Credential (Traceability Contract Signed). If one of those is missing, Partner 2 won't receive a Contract Offer. -#### Partner 1 - Access Policy Example +##### Partner 1 - Access Policy Example { "@context": { @@ -81,16 +263,15 @@ Be aware, the credential within the Summary Credential is called "TraceabilityCr All the possible mappings can be found here: https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md#0-introduction -#### Desired Outcome +##### Desired Outcome Partner 2 receives the Contract Offer because the BPNs are matching and he owns the Traceability Credential. -### Scenario 2 - -Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contract Offer if its BPN matches. But a Contract Agreement should only be created if Partner 2 also signed the Traceability Framework Agreement. So in this case, Partner 2 should receive the Contract Offer in the first place, regardless if it signed the Traceability Framework Agreement. The signing of the Agreement should be checkt at the time of contract negotiation. +#### Scenario 2 +Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contract Offer if its BPN matches. But a Contract Agreement should only be created if Partner 2 also signed the Traceability Framework Agreement. So in this case, Partner 2 should receive the Contract Offer in the first place, regardless if it signed the Traceability Framework Agreement. The signing of the Agreement should be checked at the time of contract negotiation. -#### Partner 1 - Access Policy Example +##### Partner 1 - Access Policy Example { "@context": { @@ -121,7 +302,7 @@ Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contr } } -#### Partner 1 - Usage/Contract Policy Example +##### Partner 1 - Usage/Contract Policy Example { "@context": { @@ -152,13 +333,13 @@ Partner 1 wants to create an Access Policy, that Partner 2 can receive the Contr } } -#### Desired Outcome +##### Desired Outcome Partner 2 receives the Contract Offer and is able to negotiate the contract because he owns the Traceability Credential. -### Scenario 3 +#### Scenario 3 Partner 1 wants to create an Access Policy that Partner 2 can receive the Contract Offer if the BPN is matching AND Partner 2 is identified as a Dismantler (owns the "DismantlerCredential"). -#### Partner 1 - Access Policy Example +##### Partner 1 - Access Policy Example { "@context": { @@ -197,15 +378,13 @@ Partner 1 wants to create an Access Policy that Partner 2 can receive the Contra } } -#### Desired Outcome +##### Desired Outcome Partner 2 does not receive the Contract Offer as he does not own the Dismantler Credential and is therefore not able to negotiate the contract or request the data. - - -### Scenario 4 +#### Scenario 4 Partner 1 wants to create an Access Policy that Partner 2 can receive the Contract Offer if the BPN is matching. Further, Partner 1 only wants to create an Agreement if Partner 2 is identified as a Dismantler (owns the "DismantlerCredential"). Otherwise the Negotiation has to fail. -#### Partner 1 - Access Policy Example +##### Partner 1 - Access Policy Example { "@context": { @@ -236,8 +415,7 @@ Partner 1 wants to create an Access Policy that Partner 2 can receive the Contra } } - -#### Partner 1 - Usage/Contract Policy Example +##### Partner 1 - Usage/Contract Policy Example { "@context": { @@ -268,8 +446,7 @@ Partner 1 wants to create an Access Policy that Partner 2 can receive the Contra } } -#### Desired Outcome -Partner 2 receives the Contract Offer in the first place. +##### Desired Outcome +Partner 2 receives the Contract Offer in the first place. -The contract negotiation, startet by Partner 2 fails because he has not been identified as Dismantler and therefore does not own the Dismantler Credential. - +The contract negotiation, started by Partner 2 fails because he has not been identified as Dismantler and therefore does not own the Dismantler Credential. diff --git a/package.json b/package.json index 4160bfaac..b0f3cff05 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "cx-portal-assets", - "version": "v1.6.0-RC3", + "version": "v1.6.0-RC4", "description": "Shared frontend content and static assets for the Catena-X Portal", "main": "index.js", "repository": "git@github.com:eclipse-tractusx/portal-assets.git", diff --git a/public/assets/content/de/dataspace.json b/public/assets/content/de/dataspace.json index 5f5097af7..b6169c767 100644 --- a/public/assets/content/de/dataspace.json +++ b/public/assets/content/de/dataspace.json @@ -7,21 +7,26 @@ }, { "index": 2, + "title":"Membership", + "navigation":"membership-id" + }, + { + "index": 3, "title":"BPN", "navigation":"bpn-id" }, { - "index": 3, + "index": 4, "title":"Use Case", "navigation":"usecase-id" }, { - "index": 4, + "index": 5, "title":"Roles", "navigation":"roles-id" }, { - "index": 4, + "index": 6, "title":"Links", "navigation":"links-id" } @@ -32,13 +37,18 @@ "sections": [ { "title":"Policy Beschreibung", - "description":"Policies werden verwendet, um Datenzugriffsrichtlinien sowie Nutzungsdetails zu definieren.<1><1>Zugriff bedeutet, dass definiert wird, wer auf Datenangebote zugreifen/sehen und diese anfordern kann. Die Nutzung definiert die Datennutzung, nachdem auf die Daten zugegriffen werden kann. Z.B. Unternehmen A kann auf Fahrzeugdaten von Unternehmen B zugreifen, darf diese jedoch nur für Herstellungszwecke und nicht für Marketinginhalte verwenden<1><1>Auf der folgenden Seite finden Sie Einzelheiten zu den folgenden Zugriffsrichtlinien<1> <1>", + "description":"Mithilfe von Richtlinien werden Datenzugriffsrichtlinien sowie Nutzungsdetails definiert.<1><1>'Access' bedeutet, dass festgelegt wird, wer Datenangebote sehen kann. Die Nutzung definiert den Datenzugriff selbst – also Vertragsverhandlungen und Datenverbrauch. Z.B. Unternehmen A kann sehen, dass Unternehmen B ein Datenangebot für die in der letzten Woche produzierten Fahrzeugdaten hat. Aufgrund fehlender Nutzungsrechte kann das Unternehmen die Vereinbarung/das Datenangebot jedoch nicht annehmen und hat keinen Zugriff auf diese Daten.<1>< 1>Auf der folgenden Seite finden Sie Einzelheiten zu den jeweils verfügbaren Zugriffs-/Nutzungsrichtlinien<1><1>", "imagePath":"/images/frame/AccessVsUsage.png", "backgroundColor":"#FFFFFFF", "id":"core-id", "template":"TextImageSideBySide", "sectionLink": { "data": [ + { + "title": "* Membership", + "id":"membership-id", + "internal": true + }, { "title": "* BPN", "id":"bpn-id", @@ -57,11 +67,19 @@ ] } }, + { + "title":"Datenzugriffsrichtlinie basierend auf dem Membership", + "description":"Der Mitgliedschaftsnachweis wird verwendet, um zu überprüfen, ob der Datenkonsument Mitglied des Datenraums ist. Der Mitgliedsausweis ist ein 'muss' Berechtigungsnachweis für alle Datenangebote.<1><1>", + "imagePath":"/images/logos/cx-text.svg", + "backgroundColor":"#F9F9F9", + "id":"membership-id", + "template":"TextImageSideBySide", + }, { "title":"Datenzugriffsrichtlinie basierend auf der Geschäftspartnernummer", "description":"Über die Geschäftspartnernummer (jedes Mitglied von catena-x hat einen eigenen BPN) kann der Datenzugriff eingeschränkt werden.<1><1>Das heißt, Firma a kann festlegen, dass Firma b dazu berechtigt ist Sehen Sie sich einen Datenvertrag an bzw. greifen Sie darauf zu, während Unternehmen c nicht da ist.<1><1>Beim Erstellen eines Datenangebots muss Unternehmen a entscheiden, ob das Datenangebot für eine Reihe von Unternehmen (bpns) beschränkt ist. oder nicht<1><1>", "imagePath":"/images/frame/BusinessPartnerNumber.png", - "backgroundColor":"#F9F9F9", + "backgroundColor":"#FFFFFFF", "id":"bpn-id", "template":"TextImageSideBySide", "sectionLink": { @@ -84,7 +102,7 @@ "title":"Use Cases", "description":"Unterstützte UseCase-Anmeldeinformationen: <1><1>>> Attribute - >>> CredentialSubjectItem <1><1>>> FrameworkAgreement.pcf - PcfCredential <1><1>>> FrameworkAgreement.sustainability - SustainabilityCredential <1><1>>> FrameworkAgreement.quality - QualityCredential <1><1>>> FrameworkAgreement.traceability - TraceabilityCredential <1><1>>> FrameworkAgreement.behavioraltwin - BehaviorTwinCredential <1><1>", "imagePath":"/images/logos/cx-text.svg", - "backgroundColor":"#FFFFFFF", + "backgroundColor":"#F9F9F9", "id":"usecase-id", "template":"TextImageSideBySide" }, @@ -92,14 +110,14 @@ "title":"Rollen", "description":"Dieser Text muss noch hinzugefügt werden.", "imagePath":"/images/logos/cx-text.svg", - "backgroundColor":"#F9F9F9", + "backgroundColor":"#FFFFFF", "id":"roles-id", "template":"TextImageSideBySide" }, { "title": "", "description": "", - "backgroundColor": "#FFFFFF", + "backgroundColor": "#F9F9F9", "grid": 2, "id": "links-id", "template": "LinkButtonGrid", @@ -118,8 +136,8 @@ "linksRow2": [ { "background": "#C498EF63", - "title": "coming soon", - "navigate": "/" + "title": "Hilfe zum aufsetzen von Policies im Datenangebot", + "navigate": "/documentation/?path=docs%2F02.+Technical+Integration%2F01.+Connector+Registration%2F08.+Policy+Management.md" } ] } diff --git a/public/assets/content/en/dataspace.json b/public/assets/content/en/dataspace.json index f589129da..7a21d1906 100644 --- a/public/assets/content/en/dataspace.json +++ b/public/assets/content/en/dataspace.json @@ -7,21 +7,26 @@ }, { "index": 2, + "title":"Membership", + "navigation":"membership-id" + }, + { + "index": 3, "title":"BPN", "navigation":"bpn-id" }, { - "index": 3, + "index": 4, "title":"Use Case", "navigation":"usecase-id" }, { - "index": 4, + "index": 5, "title":"Roles", "navigation":"roles-id" }, { - "index": 4, + "index": 6, "title":"Links", "navigation":"links-id" } @@ -32,13 +37,18 @@ "sections": [ { "title":"Policy Intro", - "description":"Policies are used to define data access policies as well as usage details.<1><1>Access means it defined who can access / see and request data offers. Usage defines the data ussage after the data are accessible. E.g. Company A can access vehicle data of company B but is only allowed to use them for manufacturing reasons and not marketing content<1><1>The following page provides details about the following access policies<1><1>", + "description":"Policies are used to define data access policies as well as usage details.<1><1>Access means it defined who can view data offers. Usage defines the data access itself - means contract negotiations and data consumption. E.g. Company A can see that Company B has a Data Offer of last week produced vehicle data - however due to missing usage rights the company can not accept the agreement/data offer and can't access those data.<1><1>The following page provides details about the respective available access/usage policies<1><1>", "imagePath":"/images/frame/AccessVsUsage.png", "backgroundColor":"#FFFFFFF", "id":"core-id", "template":"TextImageSideBySide", "sectionLink": { "data": [ + { + "title": "* Membership", + "id":"membership-id", + "internal": true + }, { "title": "* BPN", "id":"bpn-id", @@ -57,11 +67,19 @@ ] } }, + { + "title":"Data Access policy based on Membership", + "description":"The membership credential is used to validate if the data consumer is member of the dataspace. The membership credential is a 'must configure' credential for all data offers.<1><1>", + "imagePath":"/images/logos/cx-text.svg", + "backgroundColor":"#F9F9F9", + "id":"membership-id", + "template":"TextImageSideBySide", + }, { "title":"Data Access policy based on Business Partner Number", "description":"The business partner number (every member of catena-x has ist own bpn) can be used to restrict data access.<1><1>Means, company a can define that company b is allowed to see/access a data contract while company c isnt.<1><1>While creating a data offer, company a needs to decide if the data offer is restricted for a number of companys (bpns) or not<1><1>", "imagePath":"/images/frame/BusinessPartnerNumber.png", - "backgroundColor":"#F9F9F9", + "backgroundColor":"#FFFFFFF", "id":"bpn-id", "template":"TextImageSideBySide", "sectionLink": { @@ -84,7 +102,7 @@ "title":"Use Cases", "description":"Supported UseCase credentials: <1><1>>> Attribute - >>> CredentialSubjectItem <1><1>>> FrameworkAgreement.pcf - PcfCredential <1><1>>> FrameworkAgreement.sustainability - SustainabilityCredential <1><1>>> FrameworkAgreement.quality - QualityCredential <1><1>>> FrameworkAgreement.traceability - TraceabilityCredential <1><1>>> FrameworkAgreement.behavioraltwin - BehaviorTwinCredential <1><1>", "imagePath":"/images/logos/cx-text.svg", - "backgroundColor":"#FFFFFFF", + "backgroundColor":"#F9F9F9", "id":"usecase-id", "template":"TextImageSideBySide" }, @@ -92,14 +110,14 @@ "title":"Roles", "description":"Supported UseCase credentials: <1><1>>> Attribute - CredentialSubjectItem <1><1>>> Dismantler - DismantlerCredential <1><1>", "imagePath":"/images/logos/cx-text.svg", - "backgroundColor":"#F9F9F9", + "backgroundColor":"#FFFFFF", "id":"roles-id", "template":"TextImageSideBySide" }, { "title": "", "description": "", - "backgroundColor": "#FFFFFF", + "backgroundColor": "#F9F9F9", "grid": 2, "id": "links-id", "template": "LinkButtonGrid", @@ -118,8 +136,8 @@ "linksRow2": [ { "background": "#C498EF63", - "title": "coming soon", - "navigate": "/" + "title": "Help for setting up policies in the data supply", + "navigate": "/documentation/?path=docs%2F02.+Technical+Integration%2F01.+Connector+Registration%2F08.+Policy+Management.md" } ] }