diff --git a/docs/1-introduction-and-goals.md b/docs/1-introduction-and-goals.md index e69de29..a965dc4 100644 --- a/docs/1-introduction-and-goals.md +++ b/docs/1-introduction-and-goals.md @@ -0,0 +1,34 @@ +## 1 Introduction and goals + +The Digital Twins are no longer administrated in a central registry. The implementation of two services, "Discovery Finder" and "BPN +Discovery", ensure that Eclipse Data Space Connectors (EDC) can be found in the decentralized +environment. + +The Discovery Finder is responsible to find a matching BPN Discovery for a specific type. + +### High level requirement + +The Discovery Finder is used to find an endpoint to a BPD Discovery for a certain type and at last to find an EDC. + +### Quality goals + +- Ensure that EDCs can be found. + +- Data sovereignty is given. The provider is responsible for his data. + +- All users and services are secured and can only access when + authenticated and authorized. + +- Discovery Finder and BPN Discovery are "central" services + (horizontal and vertical scalability included) and meant to help to + connect companies. So it is integrated into the + Catena-X network with all their services. + +### Stakeholders + +| Role | Description | Goal, Intention | +|------------------|----------------------------------------------------|-------------------------------------------------------------| +| Consumer | uses a Discovery Finder | wants to find an Endpoint for a BPN Discovery to find a BPN | +| Data Provider | | 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 | + diff --git a/docs/2-architecture-constraints.md b/docs/2-architecture-constraints.md index e69de29..6b91a0a 100644 --- a/docs/2-architecture-constraints.md +++ b/docs/2-architecture-constraints.md @@ -0,0 +1,41 @@ +## 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. +With the given BPN the consumer can search for EDCs at the EDC Discovery according to this BPN. + +### Overall-View + +![Overall view](media/OverallConcept.png) + +### Architecture +A consumer can send a request to the Discovery Finder with a catalogue of different types. The Discovery Finder then will send a list of endpoint of +BPN Discoveries which are providing BPNs for the requested types. + + +### Constraints + +- Every Provider handles its own EDC / Digital Twin Registry - this + is no central service. + +- Consumer and Data Provider must have a technical user with correct user-roles + +- The Discovery Finder is a central component and must be managed by + one instance. + +### Architecture Constraints + +- Developed under an open-source license and all used frameworks and + libraries suites to this license. + +- Must be compliant and fulfill the Catena-X Guidelines. + +- The deployment is done in a Catena-X environment. So, the Discovery Finder must be able to run in a Kubernetes environment with Helm + Charts. + +- The Discovery Finder must be managed centralized. + +- Keycloak as an OAuth2 compliant authorization is needed to manage the identity and access of the user. diff --git a/docs/3-system-scope-and-context.md b/docs/3-system-scope-and-context.md index e69de29..5c4cfaa 100644 --- a/docs/3-system-scope-and-context.md +++ b/docs/3-system-scope-and-context.md @@ -0,0 +1,22 @@ +## 3 System scope and context + +### Business Context + +![](media/BusinessContext.PNG) + +| Neighbor | Description | +|---------------|------------------------------------------------------| +| Consumer App | Searches for endpoints for a given type, e.g. "oen" | +| BPN Discovery | Registers himself at startup | +| Keycloak | Is used for token validation | + + +### Technical Context + +![](media/TechnicalContext.PNG) + +| Neighbor | Description | +|---------------|--------------------------------------------------------------------------| +| Consumer App | Requests for a BPN Discovery for a certain type like "oen" | +| Keycloak | Generates token for users and provides id management of user and service | +| BPN Discovery | Registers itself at startup | diff --git a/docs/4-runtime-view.md b/docs/4-runtime-view.md index e69de29..cebe118 100644 --- a/docs/4-runtime-view.md +++ b/docs/4-runtime-view.md @@ -0,0 +1,52 @@ +## 4 Runtime-view + +### Search request + +![](media/SearchFlow.PNG) + +1. The ConsumerApp sends a request of a certain type to + DiscoveryEndpointFinderApiDelegate. + +2. DiscoveryEndpointFinderApiDelegate calls DiscoveryFinderService to + find DiscoveryEndpoints. + +3. DiscoveryFinderService calls EndpointRepository to search in + database. + +4. BPNDiscoveryService sends as a result an EndpointCollectionDto to + DiscoveryEndpointFinderApiDelegate. + +5. DiscoveryEndpointFinderApiDelegate sends a response to the + ConsumerApp with the found results. + +### Add request + +![](media/AddFlow.PNG) + +1. The Data Provider sends a request with a given endpoint to + DiscoveryEndpointFinderApiDelegate. + +2. DiscoveryEndpointFinderApiDelegate calls DiscoveryFinderService to + save this entry. Within this call the DiscoveryFinderMapper maps the + request object to an Enpoint. + +3. DiscoveryFinderService calls the EndpointRepository to save the new + entry in the database. + +### Delete request + +![](media/DeleteFlow.PNG) + +1. The Data Provider sends a request to delete an entry to + DiscoveryEndpointFinderApiDelegate. + +2. DiscoveryEndpointFinderApiDelegate calls the DiscoveryFinderService + to delete the Endpoint. + +3. DiscoveryFinderService calls UuidUtils to validate the resourceId. + +4. DiscoveryFinderService calls the EndpointRepository to find the + entry or throws an exception if the entry can't be found. + +5. DiscoveryFinderService calls the EndpointRepository to delete + finally the entry from the database. diff --git a/docs/5-deployment-view.md b/docs/5-deployment-view.md index e69de29..d6e8dff 100644 --- a/docs/5-deployment-view.md +++ b/docs/5-deployment-view.md @@ -0,0 +1,13 @@ +## 5 Deployment-view + +For Deployment needed: + +- Webserver +- Kubernetes-Cluster +- Helm + +To deploy this system, you need to use the Helm Chart in a running +Kubernetes cluster. The Helm Chart is located under +"charts/discoveryfinder". 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-discovery-finder/blob/main/README.md). diff --git a/docs/6-concepts.md b/docs/6-concepts.md index e69de29..bfc5da5 100644 --- a/docs/6-concepts.md +++ b/docs/6-concepts.md @@ -0,0 +1,115 @@ +## 6 Concept + +### Overall Concept + +The overall concept can be found under **2 Architecture and +constraints**. + +### Discovery Finder API + +The Discovery Finder is a central component in the environment. Every +consumer and data provider can call this service via the given api +endpoints. + +The api with its links can be found here: [Discovery Finder Api]( https://semantics.int.demo.catena-x.net/discoveryfinder/swagger-ui/index.html) + +#### POST [/api/administration/connectors/discovery] + +Define the endpoint to BPN discovery services and the EDC discovery +service. + +**Request body:** + +```json +{ + "type": "oen", + "description": "Service to discover BPN to a particular OEN", + "endpointAddress": "http://...", + "documentation": "http://.../swagger/index.html" +} +``` + +**Response:** + +```json +{ + "type": "oen", + "description": "Service to discover BPN to a particular OEN", + "endpointAddress": "http://...", + "documentation": "http://.../swagger/index.html", + "resourceId": "ec6f407b-4296-418c-9e4e-fb739fe72a67" +} +``` + +This service is allowed to **administrators only**. + + +#### POST [/api/administration/connectors/discovery/search] + +Find the endpoints to BPN discovery services and the EDC discovery +service. + +**Request body:** + +```json +{ +"types": + [ + "oen", + "bpid" + ] +} +``` + +**Response:** + +```json +{"endpoints": + [ + { + "type": "oen", + "description": "Service to discover BPN to a particular OEN", + "endpointAddress": "http://...", + "documentation": "http://.../swagger/index.html", + "resourceId": "ec6f407b-4296-418c-9e4e-fb739fe72a67" + }, + { + "type": "bpid", + "description": "Service to discover BPN to a particular Battery Pass ID", + "endpointAddress": "http://...", + "documentation": "http://.../swagger/index.html", + "resourceId": "08702529-3714-4c4f-b022-346b9b4fbbe2" + } + ] +} +``` + +#### DELETE [/api/administration/connectors/discovery/{resourceId}] + +Delete the endpoint to BPN discovery services and the EDC discovery service. +This service is allowed to **administrators only**. + +Path variable {resourceId} is required +Response: http Status Code 204 -> no response + +An OpenApi.yaml for this service can be found under: +"backend/src/main/resources/static/discovery-finder-openapi.yaml" [Link](https://github.com/eclipse-tractusx/sldt-discovery-finder/blob/main/backend/src/main/resources/static/discovery-finder-openapi.yaml) + + +### Security / Safety / Use of JWT Token + +The whole environment is secured with OAuth2. We used and recommend the usage of Keycloak. The Discovery Finder has +a realm entry in Keycloak. Every user who wants to use Discovery Finder +need the corresponding roles for his user. + +The roles are: + +1. [ ] *VIEW*( "view_discovery_endpoint" ) +2. [ ] *ADD*( "add_discovery_endpoint" ) +3. [ ] *DELETE*( "delete_discovery_endpoint" ) + +These roles are sent within a JWT Token generated by Keycloak. + +With all three roles it is possible to add and delete entries from the +Discovery Finder Database. For searching the view role is sufficient. +The credentials are set with entries in Helm Charts. diff --git a/docs/7-quality-scenarios.md b/docs/7-quality-scenarios.md index e69de29..ff73a4d 100644 --- a/docs/7-quality-scenarios.md +++ b/docs/7-quality-scenarios.md @@ -0,0 +1,9 @@ +## 7 Quality scenarios + +### Quality Requirements + +| Tool | Description | +|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Veracode | "Veracode enables you to quickly and cost-effectively scan software for flaws and get actionable source code analysis results."[Link](https://www.veracode.com) | +| Trivy | "Trivy is a simple and comprehensive vulnerability/misconfiguration/secret scanner for containers and other artifacts. Trivy detects vulnerabilities of OS packages and language-specific packages." [Link](https://aquasecurity.github.io/trivy/v0.34/) | +| SonarCloud | "SonarCloud's static analysis detects Bugs and Code Smells in your repositories and provides the feedback you need to write better code." [Link](https://www.sonarsource.com/products/sonarcloud/) | diff --git a/docs/documentation.md b/docs/documentation.md index a9ca27b..217c94e 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -2,4 +2,74 @@ This page provides an overview of the Discovery Finder. -## Architectural Overview \ No newline at end of file +## 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 Discovery Finder hereby is responsible to send endpoints from BPN Discoveries for a specific type. + +![Overall view](media/OverallConcept.png) + +## Actors +There are two actors who interact with the Discovery Finder + +| Actor | Description | Example | +|---------------|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------------| +| Data Consumer | The data consumer uses the Discovery Finder to search for endpoints for BPN Discoveries for a specific type. | | +| Data Provider | The data provider adds or deletes his endpoint at the Discovery Finder | A BPN Discovery registers its endpoint after startup. | +| Keycloak | Keycloak is used for token validation | | + + +## Disovery Finder Api + +The Discovery Finder provides a Swagger-Interface for all its endpoints: +https://semantics.int.demo.catena-x.net/discoveryfinder/swagger-ui/index.html + +#### Search request +![](media/search_DF.PNG) + +**Reqiest body** + +![](media/Request_Search_DF.PNG) + +**Response** + +![](media/Response_Search_DF.PNG) + +#### Add request +![add endpoint](media/setDF_Endpoint.PNG) + +**Request body** + +![request body](media/Request_Set_DF_Endpoint.PNG) + +**Response** + +![response](media/Response_Set_DF_Endpoint.PNG) + +#### Delete request +![delete endpoint](media/Delete_DF.PNG) + +ResourceID in path + +![ResourceID ](media/ResourceID_DF.PNG) + +**Response** + +![response](media/Response_Delete_DF.PNG) + +## 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 | + +## Deployment + +To deploy this system, you need to use the Helm Chart in a running +Kubernetes cluster. The Helm Chart is located under +"charts/discoveryfinder". For further information +checkout the [readme.md](https://github.com/eclipse-tractusx/sldt-discovery-finder/blob/main/README.md). diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..7921013 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,8 @@ +## Glossary** + +| Term | Description | +|----------|------------------------------------------------------------------------------------------------------------| +| Keycloak | Keycloack is an open-source Identity Management and Access management solution that allows Single Sign-On. | +| Realm | Manages a set of users, credentials, roles. Authenticates the users it controls. | +| BPN | Business Partner Number | +| EDC | Eclipse Data Space Connector | \ No newline at end of file diff --git a/docs/media/AddFlow.PNG b/docs/media/AddFlow.PNG new file mode 100644 index 0000000..ed28050 Binary files /dev/null and b/docs/media/AddFlow.PNG differ diff --git a/docs/media/BusinessContext.PNG b/docs/media/BusinessContext.PNG new file mode 100644 index 0000000..3233253 Binary files /dev/null and b/docs/media/BusinessContext.PNG differ diff --git a/docs/media/DeleteFlow.PNG b/docs/media/DeleteFlow.PNG new file mode 100644 index 0000000..a37546f Binary files /dev/null and b/docs/media/DeleteFlow.PNG differ diff --git a/docs/media/Delete_DF.PNG b/docs/media/Delete_DF.PNG new file mode 100644 index 0000000..52dd5fc Binary files /dev/null and b/docs/media/Delete_DF.PNG differ diff --git a/docs/media/OverallConcept.png b/docs/media/OverallConcept.png new file mode 100644 index 0000000..84caf03 Binary files /dev/null and b/docs/media/OverallConcept.png differ diff --git a/docs/media/Request_Search_DF.PNG b/docs/media/Request_Search_DF.PNG new file mode 100644 index 0000000..df7ea24 Binary files /dev/null and b/docs/media/Request_Search_DF.PNG differ diff --git a/docs/media/Request_Set_DF_Endpoint.PNG b/docs/media/Request_Set_DF_Endpoint.PNG new file mode 100644 index 0000000..8db8018 Binary files /dev/null and b/docs/media/Request_Set_DF_Endpoint.PNG differ diff --git a/docs/media/ResourceID_DF.PNG b/docs/media/ResourceID_DF.PNG new file mode 100644 index 0000000..6bc2746 Binary files /dev/null and b/docs/media/ResourceID_DF.PNG differ diff --git a/docs/media/Response_Delete_DF.PNG b/docs/media/Response_Delete_DF.PNG new file mode 100644 index 0000000..fefae07 Binary files /dev/null and b/docs/media/Response_Delete_DF.PNG differ diff --git a/docs/media/Response_Search_DF.PNG b/docs/media/Response_Search_DF.PNG new file mode 100644 index 0000000..d247f4a Binary files /dev/null and b/docs/media/Response_Search_DF.PNG differ diff --git a/docs/media/Response_Set_DF_Endpoint.PNG b/docs/media/Response_Set_DF_Endpoint.PNG new file mode 100644 index 0000000..fa8a8a5 Binary files /dev/null and b/docs/media/Response_Set_DF_Endpoint.PNG differ diff --git a/docs/media/SearchFlow.PNG b/docs/media/SearchFlow.PNG new file mode 100644 index 0000000..45f9010 Binary files /dev/null and b/docs/media/SearchFlow.PNG differ diff --git a/docs/media/TechnicalContext.PNG b/docs/media/TechnicalContext.PNG new file mode 100644 index 0000000..dbfad39 Binary files /dev/null and b/docs/media/TechnicalContext.PNG differ diff --git a/docs/media/drawings/AddFlow_DF.drawio b/docs/media/drawings/AddFlow_DF.drawio new file mode 100644 index 0000000..2e93e33 --- /dev/null +++ b/docs/media/drawings/AddFlow_DF.drawio @@ -0,0 +1,97 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/media/drawings/BusinessContext_DF.drawio b/docs/media/drawings/BusinessContext_DF.drawio new file mode 100644 index 0000000..3dd43a8 --- /dev/null +++ b/docs/media/drawings/BusinessContext_DF.drawio @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/media/drawings/DeleteFlow_DF.drawio b/docs/media/drawings/DeleteFlow_DF.drawio new file mode 100644 index 0000000..4b898a0 --- /dev/null +++ b/docs/media/drawings/DeleteFlow_DF.drawio @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/media/drawings/SearchFlow_DF.drawio b/docs/media/drawings/SearchFlow_DF.drawio new file mode 100644 index 0000000..31073d5 --- /dev/null +++ b/docs/media/drawings/SearchFlow_DF.drawio @@ -0,0 +1,112 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/media/drawings/TechnicalContext.drawio b/docs/media/drawings/TechnicalContext.drawio new file mode 100644 index 0000000..14f4ac3 --- /dev/null +++ b/docs/media/drawings/TechnicalContext.drawio @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/media/search_DF.PNG b/docs/media/search_DF.PNG new file mode 100644 index 0000000..52553d8 Binary files /dev/null and b/docs/media/search_DF.PNG differ diff --git a/docs/media/setDF_Endpoint.PNG b/docs/media/setDF_Endpoint.PNG new file mode 100644 index 0000000..04b3742 Binary files /dev/null and b/docs/media/setDF_Endpoint.PNG differ