diff --git a/CHANGELOG.md b/CHANGELOG.md index a51e5fc..5115d71 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## 0.5.2 +### Added +### fixed +- Change documentation folder structure + ## 0.5.1 ### Added ### fixed diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8f5898c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ + + +# Introduction +Following documentation is available: + +| Documentation | Purpose | +|-------------------------------------------------|---------------------------------------------------| +| [Arc42](architecture/) | Architecture documentation for the bpn discovery. | \ No newline at end of file diff --git a/docs/1-introduction-and-goals.md b/docs/architecture/1-introduction-and-goals.md similarity index 99% rename from docs/1-introduction-and-goals.md rename to docs/architecture/1-introduction-and-goals.md index 580d02c..ebd32fd 100644 --- a/docs/1-introduction-and-goals.md +++ b/docs/architecture/1-introduction-and-goals.md @@ -32,7 +32,6 @@ The BPN Discovery is used to find according BPNs for a given type / key combinat | Data Provider | registers his keys of a specific type in a BPN Discovery | wants that his EDC / Digital Twin can be found | | Catena-X network | provides the environment and operates the services | to enable the companies to connect and exchange data | - ### NOTICE This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/docs/2-architecture-constraints.md b/docs/architecture/2-architecture-constraints.md similarity index 99% rename from docs/2-architecture-constraints.md rename to docs/architecture/2-architecture-constraints.md index d51855a..444d3d0 100644 --- a/docs/2-architecture-constraints.md +++ b/docs/architecture/2-architecture-constraints.md @@ -1,7 +1,6 @@ ## 2 Architecture and constraints ### Overall Architecture - A consumer sends a request to the Discovery Finder with a catalogue of a certain type e.g., "bpid", "oen". The Discovery Finder responses with a list of endpoints of BPN Discoveries which provide BPNs for these kind of types. Subsequently the consumer sends a request to the given BPN Discoveries. If the BPN Discovery finds matching entries he returns a list of BPNs. diff --git a/docs/3-system-scope-and-context.md b/docs/architecture/3-system-scope-and-context.md similarity index 82% rename from docs/3-system-scope-and-context.md rename to docs/architecture/3-system-scope-and-context.md index 1bed8cb..20365a4 100644 --- a/docs/3-system-scope-and-context.md +++ b/docs/architecture/3-system-scope-and-context.md @@ -11,12 +11,12 @@ graph LR Data_Provider[Data Provider] -- "register his types and keys" --> BPN_Discovery ``` -| Neighbor | Description | -|------------------|----------------------------------------------| -| Consumer App | Searches a BPN | -| Data Provider | Registers his type and keys at BPN Discovery | -| Discovery Finder | Provides the endpoints of BPN Discoveries | -| Keycloak | Keycloak is used for token validation | +| Neighbor | Description | Example | +|------------------|-----------------------------------------------|---------------------------------------------------------------| +| Consumer App | Searches a BPN of given typ / key combination | A consumer searches for a BPN for type "oen" / key "123-oen". | +| Data Provider | Registers his type and keys at BPN Discovery | A provider add a type "oen" / key "123-oen" under his BPN. | +| Discovery Finder | Provides the endpoints of BPN Discoveries | | +| Keycloak | Keycloak is used for token validation | | ### Technical Context diff --git a/docs/4-runtime-view.md b/docs/architecture/4-runtime-view.md similarity index 100% rename from docs/4-runtime-view.md rename to docs/architecture/4-runtime-view.md diff --git a/docs/5-deployment-view.md b/docs/architecture/5-deployment-view.md similarity index 79% rename from docs/5-deployment-view.md rename to docs/architecture/5-deployment-view.md index 0554d79..64a53d5 100644 --- a/docs/5-deployment-view.md +++ b/docs/architecture/5-deployment-view.md @@ -8,10 +8,9 @@ For Deployment needed: - Helm -To deploy this system, you need to use the Helm Chart in a running -Kubernetes cluster. The Helm Chart is located under "charts/bpndiscovery". +To deploy this system, you need to use the Helm Chart in a running Kubernetes cluster. The Helm Chart is located under "charts/bpndiscovery". In case you don't have a running cluster, you can set up one by yourself -locally, using minikube. For further information checkout the [readme.md](https://github.com/eclipse-tractusx/sldt-bpn-discovery/blob/main/README.md). +locally, using minikube. For further information checkout the [readme.md](../../README.md). and [install.md](../../INSTALL.md). ### NOTICE diff --git a/docs/6-concepts.md b/docs/architecture/6-crosscutting-concepts.md similarity index 71% rename from docs/6-concepts.md rename to docs/architecture/6-crosscutting-concepts.md index c6b298b..e0020aa 100644 --- a/docs/6-concepts.md +++ b/docs/architecture/6-crosscutting-concepts.md @@ -1,9 +1,8 @@ -## 6 Concept +## 6 Crosscutting Concept ### Overall Concept -#The overall concept can be found under **2 Architecture and -constraints**. +The overall concept can be found under **2 Architecture and constraints**. ### BPN Discovery API @@ -182,7 +181,7 @@ These roles and the BPN of the requester are send within a JWT Token generated by Keycloak. With all three roles it is possible to add and delete entries from the -BPN Discovery Database. To ensure that a user only can delete its own entries the BPN of the database entry and the BPN +BPN Discovery Database. To ensure that a user only can delete its own entries the BPN of the database entry and the BPN from the Token are compared. This BPN is also used to add new entries to the BPN Discovery. If only search requests are made the view role is sufficient. @@ -191,7 +190,52 @@ The BPN Discovery registers itself at the Discovery Finder service when it starts. Therefore, the BPN Discovery has a technical user for the Discovery Finder. - +### Authentication & Authorization +The service is secured by a OAuth2 compliant authorization. Every API call has to provide a +valid Bearer Token. Authorization is provided by a role based access. These roles are possible: + +| Role | Description | +|---------------------------|----------------------------------------| +| view_bpn_discovery | can search for BPN Discovery endpoints | +| add_bpn_discovery | can add BPN Discovery endpoints | +| delete_bpn_discovery | can delete BPN Discovery endpoints | + +The Bearer Token also provide a claim with the BPN. This BPN is used to store entries. +When an entry shall be deleted this BPN is used to verify that the requester is allowed to do so. + +### Security Assessment +#### Data Flow Diagram + +```mermaid +%%{init: {"flowchart": {"curve": "linear"} }}%% +flowchart + DC(Data Consumer \n e.g. IR) + DP(Data Provider) + K(Keycloak) + + subgraph Discovery Finder + DF(Discovery Finder Backend) + DFDB[(Discovery Finder postgres)] + end + + subgraph BPN Discovery + BD(BPN Discovery Backend) + BDDB[(BPN Discovery postgres \n N instances per data \n asset type and usage)] + end + + DC <-->|Token request| K + DP <-->|Token request| K + + DF <-->|Request endpoint for given type| DC + DF <--> DFDB + K -.->|Provide public key for token validation| DF + + BD <--> BDDB + DC <-->|Request BPN for specific type| BD + DP -->|Register BPN type key| BD + BD -->|Success/error message for registration| DP + K -.->|Provide public key for token validation| BD +``` ### NOTICE diff --git a/docs/7-quality-scenarios.md b/docs/architecture/7-quality-scenarios.md similarity index 100% rename from docs/7-quality-scenarios.md rename to docs/architecture/7-quality-scenarios.md diff --git a/docs/glossary.md b/docs/architecture/glossary.md similarity index 98% rename from docs/glossary.md rename to docs/architecture/glossary.md index 5066a82..8427315 100644 --- a/docs/glossary.md +++ b/docs/architecture/glossary.md @@ -1,4 +1,4 @@ -## Glossary +## 9 Glossary | Term | Description | |----------|------------------------------------------------------------------------------------------------------------| diff --git a/docs/media/OverallConcept.png b/docs/architecture/media/OverallConcept.png similarity index 100% rename from docs/media/OverallConcept.png rename to docs/architecture/media/OverallConcept.png diff --git a/docs/documentation.md b/docs/documentation.md deleted file mode 100644 index 14cb18b..0000000 --- a/docs/documentation.md +++ /dev/null @@ -1,84 +0,0 @@ -# Developer Documentation Tractus-X BPN Discovery - -This page provides an overview of the BPN Discovery. - -## Architectural Overview -The Digital Twins are no longer administrated in a central registry. The implementation of two services, "Discovery Finder" and "BPN -Discovery", ensures that EDCs still can be found in the decentralized environment. -The BPN Discovery hereby is responsible to send BPNs for a given type / key combination e.g. for "oen"s. - -![](media/OverallConcept.png) - -## Actors -There are two actors who interact with this service. - -| Actor | Description | Example | -|---------------|-----------------------------------------------------------------------------------------------|---------------------------------------------------------------| -| Data Consumer | The Data Consumer uses the BPN Discovery to search for BPN of a given type / key combination. | A consumer searches for a BPN for type "oen" / key "123-oen". | -| Data Provider | The Data Provider adds or deletes his type / key combinations for his BPN. | A provider add a type "oen" / key "123-oen" under his BPN. | -| Keycloak | Keycloak is used for token validation | | - -## BPN Discovery Api -The BPN Discovery provides a Swagger-Interface for all endpoints: https://semantics.int.demo.catena-x.net/bpndiscovery/swagger-ui/index.html - -## Authentication & Authorization -The service is secured by a OAuth2 compliant authorization. Every API call has to provide a -valid Bearer Token. Authorization is provided by a role based access. These roles are possible: - -| Role | Description | -|---------------------------|----------------------------------------| -| view_discovery_endpoint | can search for BPN Discovery endpoints | -| add_discovery_endpoint | can add BPN Discovery endpoints | -| delete_discovery_endpoint | can delete BPN Discovery endpoints | - -The Bearer Token also provide a claim with the BPN. This BPN is used to store entries. -When an entry shall be deleted this BPN is used to verify that the requester is allowed to do so. - -## Deployment -To deploy this system, you need to use the Helm Chart in a running -Kubernetes cluster. The Helm Chart is located under "charts/bpndiscovery". For further information checkout the [readme.md](https://github.com/eclipse-tractusx/sldt-bpn-discovery/blob/main/README.md) and the [install.md](INSTALL.md). - -## Security Assessment - -### Data Flow Diagram - -```mermaid -%%{init: {"flowchart": {"curve": "linear"} }}%% -flowchart - DC(Data Consumer \n e.g. IR) - DP(Data Provider) - K(Keycloak) - - subgraph Discovery Finder - DF(Discovery Finder Backend) - DFDB[(Discovery Finder postgres)] - end - - subgraph BPN Discovery - BD(BPN Discovery Backend) - BDDB[(BPN Discovery postgres \n N instances per data \n asset type and usage)] - end - - DC <-->|Token request| K - DP <-->|Token request| K - - DF <-->|Request endpoint for given type| DC - DF <--> DFDB - K -.->|Provide public key for token validation| DF - - BD <--> BDDB - DC <-->|Request BPN for specific type| BD - DP -->|Register BPN type key| BD - BD -->|Success/error message for registration| DP - K -.->|Provide public key for token validation| BD -``` - - -### NOTICE - -This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). - -- SPDX-License-Identifier: Apache-2.0 -- SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH -- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation -- Source URL: https://github.com/eclipse-tractusx/sldt-bpn-discovery.git