diff --git a/CHANGELOG.md b/CHANGELOG.md index 55b1d582..220271fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,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.6.2 +### Added +## fixed +- Change documentation folder structure + ## 0.6.1 ### Added ## fixed diff --git a/INSTALL.md b/INSTALL.md index d8ff675c..ba634d8b 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,4 +1,4 @@ -## Deploy using Helm and K8s +# Deploy using Helm and K8s If you have a running Kubernetes cluster available, you can deploy the Registry using our Helm Chart, which is located under `charts/registry`. In case you don't have a running cluster, you can set up one by yourself locally, using [minikube](https://minikube.sigs.k8s.io/docs/start/). In the following, we will use a minikube cluster for reference. @@ -27,10 +27,10 @@ For that to work, you need to append `/etc/hosts` by running `echo "$(minikube i For automated certificate generation, use and configure [cert-manager](https://cert-manager.io/). By default, authentication is activated, please adjust `registry.authentication` if needed -## Parameters +# Parameters The Helm Chart can be configured using the following parameters (incomplete list). For a full overview, please see the [values.yaml](./backend/deployment/registry/values.yaml). -### Registry +## Registry | Parameter | Description | Default value | | --- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------| | `registry.image` | The image of the Registry | `registry:latest` | @@ -53,7 +53,7 @@ The Helm Chart can be configured using the following parameters (incomplete list | `registry.externalSubjectIdWildcardPrefix` | WildcardPrefix to make a specificAssetId visible for everyone. | `PUBLIC_READABLE` | | `registry.externalSubjectIdWildcardAllowedTypes` | List of allowed types that can be made visible to everyone. | `manufacturerPartId,assetLifecyclePhase` | -### PostgreSQL +## PostgreSQL | Parameter | Description | Default value | | --- |-------------------------------------------------------------------------------------------------------------------------------|--------------------| | `postgresql.primary.persistence.size` | Size of the `PersistentVolume` that persists the data | `50Gi` | @@ -61,15 +61,17 @@ The Helm Chart can be configured using the following parameters (incomplete list | `postgresql.auth.password` | Password for authentication at the database. If password is empty, the postgres pw will be generated random via postgres-init | `` | | `postgresql.auth.database` | Database name | `default-database` | -### Prerequisites +## Prerequisites - Kubernetes 1.19+ - Helm 3.2.0+ - PV provisioner support in the underlying infrastructure -### Required postgresql extensions +## Required postgresql extensions The application requires the following postgresql-extensions to be installed in the postgres database: | PostgreSQL Extension | Description | |----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | uuid-ossp | Via Liquibase scripts, the uuid-ossp extension will be created if it does not exist. See [liquibase-script](https://github.com/eclipse-tractusx/sldt-digital-twin-registry/blob/main/backend/src/main/resources/db/changelog/db.changelog-extensions.yaml).
In case of using Azure Database for PostgreSQL, the extension needs to be manually activated.
More details can be found at [PostgreSQL extensions in Azure Database for PostgreSQL - Flexible Server](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions) | + + diff --git a/charts/registry/README.md b/charts/registry/README.md index 41bffe54..8dc88408 100644 --- a/charts/registry/README.md +++ b/charts/registry/README.md @@ -1,6 +1,6 @@ # registry -![Version: 0.6.1](https://img.shields.io/badge/Version-0.6.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.6.1](https://img.shields.io/badge/AppVersion-0.6.1-informational?style=flat-square) +![Version: 0.6.2](https://img.shields.io/badge/Version-0.6.2-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.6.2](https://img.shields.io/badge/AppVersion-0.6.2-informational?style=flat-square) **Tractus-X Digital Twin Registry Helm Chart**
This Helm charts install the Digital Twin Registry and its dependencies. diff --git a/docs/README.md b/docs/README.md index 90b40c98..b5e5b4b2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,953 +1,29 @@ -# Developer Documentation Tractus-X Digital Twin Registry -This page provides an overview of the Digital Twin Registry and all relevant information for developers to get started with integration against the Digital Twin Registry. - -## 1 Introduction and goals -The Digital Twin Registry (DTR) acts as an address book for Digital Twins. Data Providers register their Digital Twins in the Digital Twin Registry. Data consumers query the Digital Twin Registry to find Digital Twins and interact with them further. A Digital Twin contains endpoint references to Submodel endpoints. Calling a Submodel endpoint returns data compliant to a semantic model. A semantic model describes the data that a Submodel endpoint returns. -The Digital Twin Registry is deployed as a decentralized component. That means that every Data Provider runs its own Digital Twin Registry. - -### High level requirement -The DTR acts as an address book for finding Digital Twins. - -### Quality goals - -- Ensure that Digital Twins 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. - -### Stakeholders - -| Role | Description | Goal, Intention | -|---------------|--------------------------------------------------------------|-------------------------------------------| -| Data Consumer | uses the DTR | wants to find endpoints for Digital Twins | -| Data Provider | runs its own DTR and provides endpoints to his Digital Twins | wants to provide his twins | - - -## 2 Architecture and constraints -A consumer is searching for an endpoint for a Digital Twin. For this he uses the DTR of a Data Provider. -Because now the DTR is deployed decentralized on each Data Provider side. There are some new services to help to find twins. -The whole search and the embedding of the now decentralized Digital Twin is shown below: - -### Architectural Overview- Decentralized Digital Twin Registry environment -```mermaid -graph TD - subgraph Consumer_Environment [Consumer Environment] - Consumer_Application[Consumer Application] --> Consumer_EDC[Consumer EDC] - end - - subgraph Central_Environment [Portal] - Portal_SSI[SSI] - end - - subgraph Provider_Environment[Provider Environment] - Provider_EDC --> Decentralized_DTR[Decentralized DTR] - Provider[Provider] --> |create twins| Decentralized_DTR - Keycloak -.->|get token| Provider - Keycloak -.->|get token| Provider_EDC - end - - Consumer_EDC -->|request twins| Provider_EDC - Consumer_EDC --> Central_Environment - Provider_EDC --> Central_Environment -``` - -## Asset Administration Shell Domain Model -The Asset Administration Shell Registry is an address book for Asset Administration Shell Descriptors. The diagram below, shows the domain model of the Asset Administration Shell Registry (AAS Registry).Only the main fields are shown. -```mermaid -classDiagram - AssetAdministrationShellDescriptor -- SubmodelDescriptor - AssetAdministrationShellDescriptor -- SpecificAssetId - SubmodelDescriptor -- Endpoint - Endpoint -- ProtocolInformation - - class AssetAdministrationShellDescriptor{ - +String id - } - - class SubmodelDescriptor{ - +String id - } - class Endpoint{ - -String id - } - class ProtocolInformation{ - +String href - } - class SpecificAssetId{ - +String name - +String value - } -``` - -The following table shows the synonyms for each of the domain objects above. - -| Digital Twin Registry | Asset Administration Shell Registry | -|-----------------------|-------------------------------------| -| DigitalTwin | AssetAdministrationShellDescriptor | -| Aspect | SubmodelDescriptor | -| LocalIdentifiers | SpecificAssetIds | - - -For the purpose of simplification the diagram above does only show the required fields. Below is the complete Asset Administration Shell Descriptor payload in JSON. -``` -{ - "description": [ - { - "language": "en", - "text": "complete shell example" - } - ], - "displayName": [ - { - "language": "en", - "text": "shell example" - } - ], - "assetKind": "Instance", - "assetType": "AssetType", - "globalAssetId": "c022729fe-416c-9723-f2781628fe2", - "idShort": "shell example", - "id": "69cfc420-8c1e-4212-b790-ed121820527f3", - "specificAssetIds": [ - { - "externalSubjectId": { - "type": "ExternalReference", - "keys": [ - { - "type": "AssetAdministrationShell", - "value": "TENANT_ONE" - } - ] - }, - "semanticId": { - "type": "ModelReference", - "keys": [ - { - "type": "AssetAdministrationShell", - "value": "specificAssetIdReference key" - } - ] - }, - "supplementalSemanticIds": [ - { - "type": "ExternalReference", - "keys": [ - { - "type": "BasicEventElement", - "value": "assetIdKey value" - } - ] - } - ], - "name": "testname", - "value": "testvalue" - } - ], - "submodelDescriptors": [ - { - "displayName": [ - { - "language": "de", - "text": "this is an example description1" - } - ], - "endpoints": [ - { - "interface": "interfaceNameExample", - "protocolInformation": { - "href": "edc://provider.connector:port/BPNL7588787849VQ/urn%3Auuid%3Ac227a880-b82b-40f7-846c-3942ddf26c29-urn%3Auuid%3A53125dc3-5e6f-4f4b-838d-447432b97918/submodel?content=value&extent=WithBLOBValue", - "endpointProtocol": "endpointProtocolExample", - "endpointProtocolVersion": [ - "e" - ], - "subprotocol": "subprotocolExample", - "subprotocolBody": "subprotocolBodyExample", - "subprotocolBodyEncoding": "subprotocolBodyExample", - "securityAttributes": [ - { - "type": "NONE", - "key": "Security Attribute key", - "value": "Security Attribute value" - } - ] - } - } - ], - "id": "dbf364c1-1215-43ca-98d4-f0a3d084120e3", - "semanticId": { - "type": "ExternalReference", - "keys": [ - { - "type": "Submodel", - "value": "semanticIdExample" - } - ] - }, - "supplementalSemanticId": [ - { - "type": "ExternalReference", - "keys": [ - { - "type": "Submodel", - "value": "supplementalsemanticIdExample value" - } - ] - } - ], - "description": [ - { - "language": "de", - "text": "das ist beine Beispielbeschreibung" - }, - { - "language": "en", - "text": "this is an example description" - } - ] - } - ] -} -``` - -### Constraints -- each Data Provider needs to run its own DTR in his environment. The DTR is not a central component anymore. -- Data Provider must provide his twins in its own DTR. -- To make requests to the DTR there are EDCs needed on Data Provider and Data Consumer side. - -### 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. - -- An IDM system as an OAuth2 compliant authorization is needed to manage the identity and access of the user. - -## 4 Runtime-view - -### Actors and interaction diagrams -There are two actors who interact with the AAS Registry. - -| Actor | Description | Examples | -|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| -| Data provider | The data provider runs its own Digital Twin Registry and registers AAS Descriptors and Submodel Descriptors so that consumers can query for AAS Descriptors and request data via the Submodel Descriptor Endpoints. Responsibilities: Run own Digital Twin Registry, providing EDC compatible Submodel Descriptor Endpoints, Registration of the AAS Descriptors | Any manufacturer who provides data for their assets and runs its own DTR | -| Data consumer | The data consumers are accessing the AAS Registry to discover and consume data from the Submodel Descriptor Endpoints. Responsibilities: Query the AAS Registry for AAS Descriptors, Access the Submodel Descriptor Endpoints via EDC | | - - -The interactions of both actors are shown in the diagrams below. -For the purpose of simplifying, the interactions via EDC is not shown completely. - -EDC is involved as following: -1. As a Data Provider to interact with the DTR there is no EDC needed. -2. As a Data Consumer for interactions the EDC is needed. -3. Interactions with Submodel Endpoints (Data Provider) have to be done with EDC - -### Data provider -To be able to register a DigitalTwin the following prerequisites must be met. -1. The identifiers for an asset are known (specificAssetIds, e.g. serial number, part id) -2. An endpoint that provides the data for the asset is available. The data has to be compliant with an Aspect Model. -3. To register a twin no EDC is needed. But the DTR is secured by an IDM system, so to register a technical user is needed. - -#### Register Twins (simplified without token management by IDM) - -```mermaid -sequenceDiagram - Client->>+Decentralized digital Twin registry: POST /api/v3/shell-descriptors - Decentralized digital Twin registry->>+Client: 200 Ok Response success - Note left of Client: Registers the AAS Descriptor by providing
- assetIds to make discovery possible (e.g. VIN)
- Submodel Descriptor Endpoint -``` - -### Data Provider - -#### Prerequisites -The Digital Twin Registry have to be accessed through an EDC. Following objects are needed to access the registry: - -***1. Create Data Asset*** -The EDC Data Assets represents the location of the Digital Twin Registry offered by the provider. - -| API method | URL: /management/v2/assets (POST) | -|----------------|----------------------------------------------------| -| **Parameters** | none | -| **Payload** | see below | -| **Returns** | 200 / OK | - -***Data Asset*** - -_note:_ that the "asset:prop:type" is standardized with "data.core.digitalTwinRegistry" for the Digital Twin Registry. - -``` -{ - "@context":{ - "edc":"https://w3id.org/edc/v0.0.1/ns/", - "cx-common":"https://w3id.org/catenax/ontology/common#", - "cx-taxo":"https://w3id.org/catenax/taxonomy#", - "dct":"https://purl.org/dc/terms/" - }, - "@id":"{{ASSET_ID}}", - "properties":{ - "dct:type":{ - "@id":"cx-taxo:DigitalTwinRegistry" - } - }, - "dataAddress":{ - "@type":"DataAddress", - "type":"HttpData", - "baseUrl":"{{BACKEND_SERVICE}}", - "proxyPath":"true", - "proxyBody":"true", - "proxyMethod":"true", - "proxyQueryParams":"true", - "oauth2:clientId":"{{REGISTRY_CLIENT_ID}}", - "oauth2:clientSecretKey":"{{REGISTRY_CLIENT_SECRET_KEY}}", - "oauth2:tokenUrl":"{{REGISTRY_TOKEN_ENDPOINT}}", - "oauth2:scope":"{{REGISTRY_TOKEN_SCOPE}}" - } -} -``` - -***2. Create Policy*** - -The policy is the BPN policy to give the consumer access to the asset. - - | API method | URL: /management/v2/policydefinitions (POST) | - |----------------|---------------------------------------------------| - | **Parameters** | none | - | **Payload** | see below | - | **Returns** | 200 / OK | - -***EDC Policy*** - -``` -{ - "@context": { - "odrl": "http://www.w3.org/ns/odrl/2/" - }, - "@type": "PolicyDefinitionRequestDto", - "@id": "{{POLICY_ID}}", - "policy": { - "@type": "Policy", - "odrl:permission" : [{ - "odrl:action" : "USE", - "odrl:constraint" : { - "@type": "LogicalConstraint", - "odrl:or" : [{ - "@type" : "Constraint", - "odrl:leftOperand" : "BusinessPartnerNumber", - "odrl:operator" : { - "@id": "odrl:eq" - }, - "odrl:rightOperand" : "{{CONSUMER_BPN}}" - }] - } - }] - } -} -``` - -***3. Create Contract Definition*** - -The contract definition links the created policy with the created asset. - - | API method | URL: /management/v2/contractdefinitions (POST) | - |----------------|--------------------------------------------------------------| - | **Parameters** | none | - | **Payload** | see below | - | **Returns** | 200 / OK | - - -***Contract Definition*** - -``` -{ - "@context": {}, - "@id": "{{CONTRACT_DEFINITION_ID}}", - "@type": "ContractDefinition", - "accessPolicyId": "{{ACCESS_POLICY_ID}}", - "contractPolicyId": "{{CONTRACT_POLICY_ID}}", - "assetsSelector" : { - "@type" : "CriterionDto", - "operandLeft": "{{EDC_NAMESPACE}}id", - "operator": "=", - "operandRight": "{{ASSET_ID}}" - } -} -``` - -***4. Negotiation*** - -At last both EDCs do the final negotiation and the consumer EDC receives the edr token to get access to the Digital Twin Registry. - - -#### Search for Twins (simplified) -```mermaid -sequenceDiagram - participant Service - participant ConsumerEDC as Consumer EDC - participant ProviderEDC as Provider EDC - participant DecentralDigitalTwinRegistry as Decentral Digital Twin Registry - - Service->>+ConsumerEDC: GET EDR Token - ConsumerEDC->+ProviderEDC: EDC Negotiations - ConsumerEDC-->>-Service: EDR Token - Service->>+ProviderEDC: GET lookup/shells/assetIds - ProviderEDC->>+DecentralDigitalTwinRegistry: GET lookup/shells/assetIds - DecentralDigitalTwinRegistry-->>-ProviderEDC: AssetAdministrationShellIds - ProviderEDC-->>-Service: AssetAdministrationShellIds - Service->>+ProviderEDC: GET /shell-descriptors/{aasIdentifier} - ProviderEDC->>+DecentralDigitalTwinRegistry: GET /shell-descriptors/{aasIdentifier} - DecentralDigitalTwinRegistry-->>-ProviderEDC: AssetAdministrationShellDescriptor - ProviderEDC-->>-Service: AssetAdministrationShellDescriptor - Service->>Service: Extract Endpoint - Service->>ProviderEDC: Get Endpoint (from Submodel Descriptor) - ProviderEDC-->>-Service: Endpoint -``` -## 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/registry". -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-digital-twin-registry/blob/main/README.md). - -## 6 Concept - -### Overall Concept - -The overall concept can be found under **2 Architecture and constraints**. - -### Asset Administration Shell specification -The Digital Twin Registry has implemented Asset Administration Shell specification in version 3.0. -The corresponding openapi file can be found here: "backend/src/main/resources/static/aas-registry-openapi.yaml" - -### Uniqueness -The following table contains the identifier fields and whether they are globally unique, unique for an -AAS Descriptor or not unique at all. - -| Field | Unique globally | Explanation | -|----------------------------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| AssetAdministrationShellDescriptor#id | yes | - | -| AssetAdministrationShellDescriptor#specificAssetIds#key | - | The specificAssetIds are primarily used for searches. There are use cases where multiple values for the same key can exist. For instance, an OEM can have multiple World Manufacturer Identifier (WMI). Queries against any of the WMI must be possible as data consumers may know only one of the WMI. | -| AssetAdministrationShellDescriptor#submodelDescriptor#id | yes | - | - -Uniqueness for natural keys e.g. serial numbers is not given in the manufacturing world. -Therefore, the AAS Registry cannot enforce uniqueness for natural keys (specificAssetIds). - -### Identifiers - -#### Identification and globalAssetId - -| Field | Value | Description | -|-----------------------------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| AssetAdministrationShellDescriptor#id | Random UUIDv4 | - | -| AssetAdministrationShellDescriptor#globalAssetId[0] | Random UUIDv4 | The globalAssetId is a natural key that identifies an asset uniquely. An example for instance is the MAC - Address. In the manufacturing industry not all assets do have a global unique natural key. It was decided therefore to use a random UUID. | -| SubmodelDescriptor#id | Random UUIDv4 | - | - - -### Predefined specificAssetIds -The `specificAssetIds` are collection key-value pairs and the fundamental part for discovery capabilities of the AAS Registry. Data consumers use these specificAssetIds to find AAS Descriptors. -In multiple discussions with different Product Owners and architects, the keys for `specificAssetIds` were defined. -The AAS Registry does not enforce any `specificAssetId key`. However, data providers should use one of these keys if the Asset Administration Shell Descriptor does match one of the defined types e.g. Serial Part, Vehicle. -If you do not find a matching `specificAssetId` key for your use case please contact us so that we can extend the list. - -### Submodel Descriptor Endpoints -The Submodel Descriptor contains all the required information to obtain data from a remote address. -The endpoint for a Submodel Descriptor must be setup as follows: - -| Property | Description | Example Value | -|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| interface | The type of the endpoint. Only "EDC" is currently supported. | EDC | -| semanticId | The urn of the Semantic Model that describes the data of this endpoint. | urn:bamm:com.catenax:1.0.0#ExampleModel | -| protocolInformation#href | The EDC compatible endpoint where the semanticId compatible data can be fetched. Catena-X defined the URL structure as: Read Endpoint: http:////-/submodel?content=value Operations Endpoint: /invoke?content=value | Read Endpoint: http://myawesomeconnector.com/BPNL7588787849VQ/urn%3Auuid%3Ac227a880-b82b-40f7-846c-3942ddf26c29-urn%3Auuid%3A53125dc3-5e6f-4f4b-838d-447432b97918/submodel?content=value&extent=WithBLOBValue | -| Operation Endpoint: http://myawesomeconnector.com/BPNL7588787849VQ/urn%3Auuid%3Ac227a880-b82b-40f7-846c-3942ddf26c29-urn%3Auuid%3A53125dc3-5e6f-4f4b-838d-447432b97918/submodel/vin-van-converter/invoke?content=value | | | -| protocolInformation#endpointProtocol | The protocol of the endpoint. | HTTPS | -| protocolInformation#endpointProtocolVersion | The version of the protocol. | 1.0 | - -### Authentication & Authorization -The AAS Registry needs to be integrated with an OAuth2 compliant authorization server. Every API call has to provide a valid Bearer Token issued by this authorization server. -Authorization is supported by Role Based Access Control (RBAC). Following roles are available: - -| Role | Description | -|-------------------------|----------------------------------------------------------| -| view_digital_twin | Can read all digital twins. | -| add_digital_twin | Can add a digital twin. | -| update_digital_twin | Can update a digital twin. | -| delete_digital_twin | Can delete a digital twin. | -| submodel_access_control | Can perform submodel access control authorization calls. | -| read_access_rules | Can read the rules defined for access control. | -| write_access_rules | Can write the rules defined for access control. | - -Depending on being a Data Provider or a Data Consumer there are different tokens for authentication and authorization needed. -#### Data Provider -1. technical user for the service which administrates the Digital Twin Registry -2. technical user for the EDC which makes the requests in behalf of the Data Consumer to the DTR. - -#### Data Consumer -1. needs an EDR token which is provided between the intercommunication between the EDCs. - -#### AWS Cognito as Identity Provider -DTR can support Keycloak and AWS Cognito as an Identity Provider for all clients that want to access the registry. -Client must fetch a token and send it together with the request. -Cognito behaves somehow different than Keycloak so some code modifications were necessary to use Cognito as an Identity Provider for DTR. -Detailed information can be found [here](COGNITO.md) - -### Authentication on behalf of a user -The AAS Registry can be accessed on behalf of a user. The token has to be obtained via the OpenID Connect flow. The AAS Registry will validate these tokens. -*Support contact* tractusx-dev@eclipse.org - -### Access control to Digital Twins Based on the BPN (Business Partner Number)/ TenantId - -#### Classic implementation - -The visibility of `specificAssetIds` in the Digital Twin Registry based on the Business Partner Number (BPN) (Which is send via header Edc-Bpn) can be controlled with the attribute `externalSubjectId`. Hence, the `externalSubjectId` is identified with the BPN. -The communication between consumer and provider is via EDC. Before the provider EDC sends the request to the DTR, the property Edc-Bpn with the BPN of the consumer will be set by the provider EDC. - - -* The BPN as attribute to a *specificAssetId* can be optionally provided in `specificAssetIds`. This can be done with `externalSubjectId`. -* Only those users, where `externalSubjectId` matches the Eclipse Dataspace Components-Header (Edc-Bpn -> *i.e.* BPN) are able to discover and read exactly this content of `specificAssetIds`. -* The behavior is **closed by default**, *i.e.*, if no `externalSubjectId` is defined to a `specificAssetId`, the content of this particular `specificAssetId` (key, value) is only visible for the owner of the *Digital Twin* (also known as data provider). -* To mark a `specificAssetId` as public for every reader on a *Digital Twin*, the defined characters (`"PUBLIC_READABLE"`) need to be added in the `externalSubjectId`. - * *Cave: The publisher of `specificAssetIds` needs to consider antitrust law. This use of `"PUBLIC_READABLE"` is only allowed for the *specificAssetId* `"assetLifecyclePhase"` and `"manufacturerPartId"` (which is technically enforced by the Digital Twin Registry) if its content describes material numbers of products and those products are or were in serial production for the open market. If its content describes material numbers of products in state of, *e.g.*, pre-production, being planned for production, being unsold, the use of `"PUBLIC_READABLE"` is not allowed and use of dedicated read access via `externalSubjectId` is to be used instead. `"manufacturerPartId"` is not allowed to be used for different content than the one described here.* -* The behavior of the Digital Twin Registry is as follows. The read-access from `specificAssetIds` is inherited by the other fields of a *Digital Twin*. - * An owner and a user with respect to the BPN, who has read-access to one of the `specificAssetIds` (`externalSubjectId` has `"value":""`) has read-access to the other fields of a *Digital Twin* as well, *i.e.* (see the full list of fields [POST Asset Administration Shell Descriptor v3.0 SSP-001](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.0_SSP-001#/Asset%20Administration%20Shell%20Registry%20API/PostAssetAdministrationShellDescriptor)) - * `description` - * `displayName` - * `administration` - * `assetKind` - * `assetType` - * `globalAssetId` - * `idShort` - * `id` - * `submodelDescriptors` - * `specificAssetIds` - - * A user, who has only general read-access to `specificAssetIds` (`externalSubjectId` has `"value":"PUBLIC_READABLE"`) has only read-access to the following fields of a *Digital Twin* - * `id` - * `submodelDescriptors` - * `specificAssetIds` - * The list of `keys` in the externalSubjectId is filtered for the requested user. Only the keys will be returned where the BPN matched. - -**Hint**
-The defined string for `"PUBLIC_READABLE"` and the list of allowed types to mark as public is configurable via helm values.yml: -* `registry.externalSubjectIdWildcardPrefix` (Default is `"PUBLIC_READABLE"` ) -* `registry.externalSubjectIdWildcardAllowedTypes` (Default is `"manufacturerPartId,assetLifecyclePhase"` ) - -Detailed information can be found [here](../INSTALL.md) -_________________ - - - -Example to create a *Digital Twin* with `specificAssetIds`: -``` -POST Method: -{{registry-baseurl}}/api/v3/shell-descriptors -``` - -```json -POST Body (JSON): -{ - "idShort":"idShortExample", - "id":"e1eba3d7-91f0-4dac-a730-eaa1d35e035c-2", - "description":[ - { - "language":"en", - "text":"Example of human readable description of digital twin." - } - ], - "specificAssetIds":[ - { - "name":"partInstanceId", - "value":"24975539203421" - }, - { - "name":"customerPartId", - "value":"231982", - "externalSubjectId":{ - "type":"ExternalReference", - "keys":[ - { - "type":"GlobalReference", - "value":"BPN_COMPANY_001" - } - ] - } - }, - { - "name":"manufacturerId", - "value":"123829238", - "externalSubjectId":{ - "type":"ExternalReference", - "keys":[ - { - "type":"GlobalReference", - "value":"BPN_COMPANY_001" - }, - { - "type":"GlobalReference", - "value":"BPN_COMPANY_002" - } - ] - } - }, - { - "name":"manufacturerPartId", - "value":"231982", - "externalSubjectId":{ - "type":"ExternalReference", - "keys":[ - { - "type":"GlobalReference", - "value":"PUBLIC_READABLE" - } - ] - } - } - ], - "submodelDescriptors":[ - { - "endpoints":[ - { - "interface":"SUBMODEL-3.0", - "protocolInformation":{ - "href":"https://edc.data.plane/mypath/submodel", - "endpointProtocol":"HTTP", - "endpointProtocolVersion":[ - "1.1" - ], - "subprotocol":"DSP", - "subprotocolBody":"body with information required by subprotocol", - "subprotocolBodyEncoding":"plain", - "securityAttributes":[ - { - "type":"NONE", - "key": "NONE", - "value": "NONE" - } - ] - } - } - ], - "idShort":"idShortExample", - "id":"cd47615b-daf3-4036-8670-d2f89349d388-2", - "semanticId":{ - "type":"ExternalReference", - "keys":[ - { - "type":"Submodel", - "value":"urn:bamm:io.catenax.serial_part_typization:1.1.0#SerialPartTypization" - } - ] - }, - "description":[ - { - "language":"de", - "text":"Beispiel einer lesbaren Beschreibung des Submodels." - }, - { - "language":"en", - "text":"Example of human readable description of submodel" - } - ] - } - ] -} -``` -This example is a *Digital Twin* with four different `specificAssetIds` as descriptors. -* `partInstanceID` is discoverable and visible only for the owner of the *Digital Twin*, since no `externalSubjectId` is defined. -* `customerPartId` is discoverable and visible only for the owner of the *Digital Twin* and an (external) reader via EDC, who has the bpn-value "BPN_COMPANY_001" in the header of the EDC -* `manufacturerId` is discoverable and visible only for the owner of the *Digital Twin* and two (external) readers via EDC, who have the bpn-value "BPN_COMPANY_001" and "BPN_COMPANY_002" in the header of the EDC -* `manufacturerPartId` is discoverable and visible for everyone, who has access to the Digital Twin Registry, because the `externalSubjectId` has the value `"PUBLIC_READABLE"` included. - -For example, if an (external) reader via EDC requests the here shown *Digital Twin* and the edc-bpn header includes the bpn-value "BPN_COMPANY_001", the list of `specificAssetIds` contains three entries, namely: -* `customerPartId` -* `manufacturerId` -* `manufacturerPartId` - -In consequence, the reader "BPN_COMPANY_001", as well as the reader "BPN_COMPANY_002" and the owner of this *Digital Twin* has full read access to the other fields of this *Digital Twin*, *i.e.* `idShort`, `id`, `description`, and `submodelDescriptors`. - -In this example, the `specificAssetId` `"name": "partInstanceId"` is filtered out, because it is only visible for the owner of the *Digital Twin*. - -Any (external) readers with respect to the `"PUBLIC_READABLE"` flag at `specificAssetId` `"name": "manufacturerPartId"`, have access to the fields -* `id` -* `submodelDescriptors` - -of this *Digital Twin*. - -#### Granular access control implementation - -The granular access control implementation is provided as an alternative option to enforce visibility rules of the *Digital Twin* details. These can be: - -1. The visibility of the *Digital Twin* as a whole -2. The visibility of certain `specificAssetId` names and values of the *Digital Twin* -3. The visibility of certain `submodelDescriptors` of the *Digital Twin* -4. Restricting access to *Digital Twin* details which are `"PUBLIC_READABLE"` - (only showing the `id`, the public readable `specificAssetId` names and values, the `createdDate` and the filtered `submodelDescriptors` ) - -> [!NOTE] -> We have created an EDC extension to let you leverage the benefits of granular access control to the full extent. Please read the related details [here](EDC-extension-configuration.md)! - -##### Configuring granular access control - -To enable granular access control (instead of the classic implementation), the `registry.useGranularAccessControl` configuration HELM chart property must be set to `"true"`. -This will in turn set `registry.use-granular-access-control` Spring property to `true`, which will activate the granular access control. - -In addition to the aforementioned property, we can set the number of records fetched when listing records. This can be done by setting the -`registry.granularAccessControlFetchSize` HELM chart property. The default value is `"500"`. Providing this property will set the `registry.granular-access-control-fetch-size` -Spring property of the Digital Twin Registry to the equivalent int value. In general, the higher we can set this value, the fewer fetches will be required when shells are -listed and filtered. It is recommended to use at least 1000 if the registry has more than 100 000 Digital Twins. - -##### Creating an access rule - -The access rules can be managed using the provided access rule API ([See API specs here](../access-control-service-sql-impl/src/main/resources/static/access-control-openapi.yaml)). - -> [!NOTE] -> In order to use the API, the client must have the `read_access_rules` and `write_access_rules` roles. - -Please refer to the following table to get familiar with the schema of the access rules. - -| Property | Type | Required on create | Description | -|-------------|----------|--------------------|----------------------------------------------------------------------------------------| -| id | long | No (read-only) | The auto-incremented Id of the rule. | -| tid | string | No (read-only) | The Id of the owner tenant (the owner of the Digital Twin Registry). | -| policyType | enum | Yes | Defines the policy language used for the rule's policy. Possible values: `AAS`. | -| policy | json | Yes | The definition of the access rule. | -| description | string | No (optional) | An short, optional description or note to help with the maintenance of the rule. | -| validFrom | datetime | No (optional) | An optional timestamp representing the earlier time when the rule should be in effect. | -| validTo | datetime | No (optional) | An optional timestamp representing the latest time when the rule should be in effect. | - -An example policy: - -```json -{ - "id": 1, - "tid": "00000000-1111-2222-3333-444444444444", - "policyType": "AAS", - "policy": { - "accessRules": [ - { - "attribute": "bpn", - "operator": "eq", - "value": "BPNL00000000000A" - }, - { - "attribute": "mandatorySpecificAssetIds", - "operator": "includes", - "values": [ - { - "attribute": "manufacturerPartId", - "operator": "eq", - "value": "99991" - }, - { - "attribute": "customerPartId", - "operator": "eq", - "value": "ACME001" - } - ] - }, - { - "attribute": "visibleSpecificAssetIdNames", - "operator": "includes", - "values": [ - { - "attribute": "name", - "operator": "eq", - "value": "manufacturerPartId" - }, - { - "attribute": "name", - "operator": "eq", - "value": "customerPartId" - }, - { - "attribute": "name", - "operator": "eq", - "value": "partInstanceId" - } - ] - }, - { - "attribute": "visibleSemanticIds", - "operator": "includes", - "values": [ - { - "attribute": "modelUrn", - "operator": "eq", - "value": "Traceabilityv1.1.0" - }, - { - "attribute": "modelUrn", - "operator": "eq", - "value": "ProductCarbonFootprintv1.1.0" - } - ] - } - ] - }, - "description": "Access rule description.", - "validFrom": "2024-01-02T03:04:05Z", - "validTo": "2024-06-07T08:09:10Z" -} -``` - -The example policy above can be split into multiple parts when read. - -1. Validity - It is valid between `2024-01-02T03:04:05Z` and `2024-06-07T08:09:10Z`. Otherwise, it is ignored. -2. Scope - Outlining when a rule is applicable. - 1. The first access rule (`$.policy.accessRules[0]`) defines the *bpn* (*externalSubjectId*) of the tenant to whom the policy applies. - 2. The second access rule (`$.policy.accessRules[1]`) defines the *mandatorySpecificAssetIds* which must be present in the *Digital Twin* in order for the rule to be applicable. The rule will become applicable only if __all__ *specificAssetId* name-value pairs of the rule are present in the *Digital Twin*. -3. Effect - Defines which parts of the matching *Digital Twins* should be visible when the client's *externalSubjectId* matches the rule's. - 1. The third access rule (`$.policy.accessRules[2]`) defines the *visibleSpecificAssetIdNames*. When the rule matches, the *specificAssetIds* from the - *Digital Twin* with these names should be visible using one of the cases below: - 1. When the same name is present as a name in the *mandatorySpecificAssetIds* and the *visibleSpecificAssetIdNames*, then the rule will only make a - *specificAssetId* from the *Digital Twin* when the *specificAssetId* is listed as an item of the *mandatorySpecificAssetIds*. - 2. Otherwise, if the name is only present as a *visibleSpecificAssetIdNames* without being present on the *mandatorySpecificAssetIds* as well, the rule - will make visible any *specificAssetId* from the *Digital Twin* if the name of the *specificAssetId* matches the name from the *visibleSpecificAssetIdNames*, - regardless of the value of the *specificAssetId* in the *Digital Twin*. - 2. The fourth access rule (`$.policy.accessRules[3]`) defines the *visibleSemanticIds*. These *semanticIds* are identifying the *submodelDescriptors* from the *Digital Twin* which should be visible when the rule matches. - -##### How the rule evaluation works? - -In general, when a shell's visibility is evaluated, we must: - -1. Take the *externalSubjectId* of the client, the *ownerTenantId* of the *Digital Twin Registry* and the contents of the *Digital Twin* in question. -2. If the *externalSubjectId* is equal to the *ownerTenantId*, the client can see the full content. -3. Otherwise, we must fetch all access rules which belong to the client's *externalSubjectId* or `PUBLIC_READABLE`; and is in the specified validity period -4. Then, for each *specificAssetId* of the *Digital Twin*, we must verify whether there is at least one applicable rule that gives access to the *specificAssetId* of the *Digital Twin*. -5. Similarly, for each *submodelDescriptor* of the *Digital Twin*, we must verify whether there is at least one applicable rule that gives access to the *semanticId* of the *submodelDescriptor* from the *Digital Twin*. - -The process acn be summed up in a more visual way as shown in the diagram below: - -```mermaid -flowchart LR - START - START-->isAdmin{Is\nexternalSubjectId\n=\nownerTenantId?} - isAdmin-- no -->fetchRules[Fetch valid rules\nfor externalSubjectId\nor PUBLIC_READABLE] - isAdmin-- yes -->showAll[Show full content] - fetchRules-->anyRules{Any rules found?} - anyRules-- yes -->startForEach((For each rule)) - startForEach-->isRuleMatching{Is the\nrule matching\nthe Digital Twin?} - isRuleMatching-- no -->endForEach((For each rule)) - isRuleMatching-- yes -->applyRule[Apply rule effect] - applyRule-->endForEach - endForEach-->isShellVisible{Is the\nDigital Twin\nvisible?} - isShellVisible-- yes -->showFiltered[Show filtered Digital Twin] - isShellVisible-- no -->denied[Hide Digital Twin] - anyRules-- no -->denied - showAll-->END - denied-->END - showFiltered-->END -``` - -###### Lookup shells - `GET {{baseUrl}}/api/v3/lookup/shells?assetIds=...` - -In case of the lookup shells, the filtering and access control of the *Digital Twins* is done using the following steps: - -1. A page (fetchSize) of *Digital Twins* is loaded which are matching the client's query expression. -2. The list of shells fetched in the previous step is filtered by applying the access control rules to them one-by-one. -3. The process is repeated until we have the desired number of *Digital Twins* or there are no more *Digital Twins* to fetch. -4. The AAS Ids of the visible *Digital Twins* are returned. - -###### Get all shells - `GET {{baseUrl}}/api/v3/shell-descriptors` - -The process is similar to the lookup shells, the filtering and access control of the *Digital Twins* is done as follows: - -1. A page (fetchSize) of *Digital Twins* is loaded. -2. The list of shells fetched in the previous step is filtered by applying the access control rules to them one-by-one. -3. The process is repeated until we have the desired number of *Digital Twins* or there are no more *Digital Twins* to fetch. -4. The visible properties of the visible *Digital Twins* are returned. - 1. If the list of *specificAssetIds* in the shell has *multiple* entries with the same name, then the following rules apply: - 1. Usecase 1: A rule includes a specificAssetId (for example customerPartId=123) as *mandatorySpecificAssetId and visibleSpecificAssetId*. The Shell has multiple entries with the same name and *one of the entry* matched the value from mandatorySpecificAssetId, then only the matched entry is visible. - 2. Usecase 2: A rule includes a specificAssetId (for example customerPartId=123) as *mandatorySpecificAssetId and visibleSpecificAssetId*. The Shell has multiple entries with the same name and *none of the entries* matched the value from mandatorySpecificAssetId, then no entries with the same name is visible. - -###### Get Shell by AAS Id - `GET {{baseUrl}}/api/v3/shell-descriptors/:aasIdentifier` - -To determine the visibility of a single *Digital Twin*, we can simply: - -1. Fetch the *Digital Twin* -2. Apply the access control rules using the process defined at the beginning of this section -3. Return the visible parts of the *Digital Twin* (or empty result in case the *Digital Twin* is not visible at all) - -#### Public readable - -When a *Digital Twin* is only visible because there are applicable `PUBLIC_READABLE` rules which make certain properties visible, -the shell details are further limited. This means, that we are returning only: - -- the `id`, -- the `idEsternal` (*AAS Id*), -- the public readable `specificAssetId` names and values, -- the `createdDate` -- the filtered `submodelDescriptors` - - -## 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/) | - -## Security Assessment - -Data flow diagram: - -```mermaid -%%{init: {"flowchart": {"curve": "linear"} }}%% -graph TB - CD[Consumer Data] - CE[Consumer EDC] - PE[Provider EDC] - DP[Data Provider] - IDM[IDM] - DTR-B[DTR Backend] - DTR-P[DTR Postgres] - - subgraph Provider Env - PE - DP - IDM - subgraph Digital Twin Registry - DTR-B - DTR-P - end - end - - CD <-->|X-API auth key \n return twin| CE - CE <-->|EDC flow \n certificate based auth \n provide role| PE - - PE -->|Get token| IDM - DP -->|Get token| IDM - DTR-B -->|Get public key \n token validation| IDM - - PE <-->|Get twin & submodel| DTR-B - DP <-->|Register twin & submodel| DTR-B - DTR-B <-->|Create twin & submodel| DTR-P -``` - -## Glossary - -| Term | Description | -|---------------|----------------------------------------------------------------------------------------------------------------| -| EDC | Eclipse Data Space Connector | -| DTR | Digital Twin Registry - the phone book to register and to search for endpoints for Digital Twins | -| dDTR | decentralized Digital Twin Registry - the Digital Twin Registry which is deployed on each Data Provider system | -| Data Provider | deploys a own Digital Twin Registry and provides the data for his digital twins | -| Data Consumer | uses the Digital Twin Registry to search for digital twins | -| IDM | User identity management e.g. Keycloak | - -## Remarks -The Digital Twin Registry implementation is not 100 % specification compliant. - -### 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-digital-twin-registry.git + + +# Introduction +Following documentation is available: + +| Documentation | Purpose | +|----------------------------------------------------------------------------|---------------------------------------------------------------------| +| [Arc42](architecture/) | Architecture documentation for the discovery finder. | +| [Guideline to use aws-cognito](guideline-aws-cognito-configuration.md) | Documentation to use aws cognito as identity provider | +| [Guideline to use edc-extension](guideline-edc-extension-configuration.md) | Documentation to build and use the edc extension for access control | +| [Development](development/) | Useful collections for development | \ No newline at end of file diff --git a/docs/architecture/1-introduction-and-goals.md b/docs/architecture/1-introduction-and-goals.md new file mode 100644 index 00000000..c68e8dd2 --- /dev/null +++ b/docs/architecture/1-introduction-and-goals.md @@ -0,0 +1,28 @@ +## 1 Introduction and goals +The Digital Twin Registry (DTR) acts as an address book for Digital Twins. Data Providers register their Digital Twins in the Digital Twin Registry. Data consumers query the Digital Twin Registry to find Digital Twins and interact with them further. A Digital Twin contains endpoint references to Submodel endpoints. Calling a Submodel endpoint returns data compliant to a semantic model. A semantic model describes the data that a Submodel endpoint returns. +The Digital Twin Registry is deployed as a decentralized component. That means that every Data Provider runs its own Digital Twin Registry. + +### High level requirement +The DTR acts as an address book for finding Digital Twins. + +### Quality goals + +- Ensure that Digital Twins 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. + +### Stakeholders + +| Role | Description | Goal, Intention | +|---------------|--------------------------------------------------------------|-------------------------------------------| +| Data Consumer | uses the DTR | wants to find endpoints for Digital Twins | +| Data Provider | runs its own DTR and provides endpoints to his Digital Twins | wants to provide his twins | + +### 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: 2024 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-digital-twin-registry.git \ No newline at end of file diff --git a/docs/architecture/2-architecture-constraints.md b/docs/architecture/2-architecture-constraints.md new file mode 100644 index 00000000..8e21c68d --- /dev/null +++ b/docs/architecture/2-architecture-constraints.md @@ -0,0 +1,207 @@ +## 2 Architecture and constraints +A consumer is searching for an endpoint for a Digital Twin. For this the user uses the DTR of a Data Provider, because the DTR is deployed decentralized on each Data Provider side. +There are some new services to help to find twins. +The whole search and the embedding of the decentralized Digital Twin is shown below: + +### Architectural Overview- Decentralized Digital Twin Registry environment +```mermaid +graph TD + subgraph Consumer_Environment [Consumer Environment] + Consumer_Application[Consumer Application] --> Consumer_EDC[Consumer EDC] + end + + subgraph Central_Environment [Portal] + Portal_SSI[SSI] + end + + subgraph Provider_Environment[Provider Environment] + Provider_EDC --> Decentralized_DTR[Decentralized DTR] + Provider[Provider] --> |create twins| Decentralized_DTR + Keycloak -.->|get token| Provider + Keycloak -.->|get token| Provider_EDC + end + + Consumer_EDC -->|request twins| Provider_EDC + Consumer_EDC --> Central_Environment + Provider_EDC --> Central_Environment +``` + +### Asset Administration Shell Domain Model +The Asset Administration Shell Registry is an address book for Asset Administration Shell Descriptors. The diagram below, shows the domain model of the Asset Administration Shell Registry (AAS Registry).Only the main fields are shown. +```mermaid +classDiagram + AssetAdministrationShellDescriptor -- SubmodelDescriptor + AssetAdministrationShellDescriptor -- SpecificAssetId + SubmodelDescriptor -- Endpoint + Endpoint -- ProtocolInformation + + class AssetAdministrationShellDescriptor{ + +String id + } + + class SubmodelDescriptor{ + +String id + } + class Endpoint{ + -String id + } + class ProtocolInformation{ + +String href + } + class SpecificAssetId{ + +String name + +String value + } +``` + +The following table shows the synonyms for each of the domain objects above. + +| Digital Twin Registry | Asset Administration Shell Registry | +|-----------------------|-------------------------------------| +| DigitalTwin | AssetAdministrationShellDescriptor | +| Aspect | SubmodelDescriptor | +| LocalIdentifiers | SpecificAssetIds | + + +For the purpose of simplification the diagram above does only show the required fields. Below is the complete Asset Administration Shell Descriptor payload in JSON. +``` +{ + "description": [ + { + "language": "en", + "text": "complete shell example" + } + ], + "displayName": [ + { + "language": "en", + "text": "shell example" + } + ], + "assetKind": "Instance", + "assetType": "AssetType", + "globalAssetId": "c022729fe-416c-9723-f2781628fe2", + "idShort": "shell example", + "id": "69cfc420-8c1e-4212-b790-ed121820527f3", + "specificAssetIds": [ + { + "externalSubjectId": { + "type": "ExternalReference", + "keys": [ + { + "type": "AssetAdministrationShell", + "value": "TENANT_ONE" + } + ] + }, + "semanticId": { + "type": "ModelReference", + "keys": [ + { + "type": "AssetAdministrationShell", + "value": "specificAssetIdReference key" + } + ] + }, + "supplementalSemanticIds": [ + { + "type": "ExternalReference", + "keys": [ + { + "type": "BasicEventElement", + "value": "assetIdKey value" + } + ] + } + ], + "name": "testname", + "value": "testvalue" + } + ], + "submodelDescriptors": [ + { + "displayName": [ + { + "language": "de", + "text": "this is an example description1" + } + ], + "endpoints": [ + { + "interface": "interfaceNameExample", + "protocolInformation": { + "href": "edc://provider.connector:port/BPNL7588787849VQ/urn%3Auuid%3Ac227a880-b82b-40f7-846c-3942ddf26c29-urn%3Auuid%3A53125dc3-5e6f-4f4b-838d-447432b97918/submodel?content=value&extent=WithBLOBValue", + "endpointProtocol": "endpointProtocolExample", + "endpointProtocolVersion": [ + "e" + ], + "subprotocol": "subprotocolExample", + "subprotocolBody": "subprotocolBodyExample", + "subprotocolBodyEncoding": "subprotocolBodyExample", + "securityAttributes": [ + { + "type": "NONE", + "key": "Security Attribute key", + "value": "Security Attribute value" + } + ] + } + } + ], + "id": "dbf364c1-1215-43ca-98d4-f0a3d084120e3", + "semanticId": { + "type": "ExternalReference", + "keys": [ + { + "type": "Submodel", + "value": "semanticIdExample" + } + ] + }, + "supplementalSemanticId": [ + { + "type": "ExternalReference", + "keys": [ + { + "type": "Submodel", + "value": "supplementalsemanticIdExample value" + } + ] + } + ], + "description": [ + { + "language": "de", + "text": "das ist beine Beispielbeschreibung" + }, + { + "language": "en", + "text": "this is an example description" + } + ] + } + ] +} +``` + +### Constraints +- each Data Provider needs to run its own DTR in his environment. The DTR is not a central component anymore. +- Data Provider must provide his twins in its own DTR. +- To make requests to the DTR there are EDCs needed on Data Provider and Data Consumer side. + +### 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. + +- An IDM system as an OAuth2 compliant authorization is needed to manage the identity and access of the user. + +### 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: 2024 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-digital-twin-registry.git \ No newline at end of file diff --git a/docs/architecture/3-system-scope-and-context.md b/docs/architecture/3-system-scope-and-context.md new file mode 100644 index 00000000..be3fd8ce --- /dev/null +++ b/docs/architecture/3-system-scope-and-context.md @@ -0,0 +1,48 @@ +## 3 System scope and context + +### Business Context +```mermaid +graph LR + Consumer_Edc[Consumer EDC] -- "request shell" --> Provider_Edc[Provider EDC] + Provider_Edc -- "call DTR" --> DTR[Digital Digital Twin Registry] + Provider_App[Provider App] -- "create/delete Shells" --> DTR + DTR -- "response with shell" --> Provider_Edc + Keycloak -- "administrates the authorization token" <--> DTR + Provider_Edc -- "response with shell" --> Consumer_Edc +``` + +| Neighbor | Description | +|--------------|-------------------------------------------------------------------| +| Consumer EDC | Search for shells | +| Provider EDC | Retrieve the request from Consumer EDC and calls DTR | +| Keycloak | Keycloak is used for token validation | +| Provider App | The provider is responsible for the data and create/delete shells | + + +### Technical Context +```mermaid +graph LR + Consumer_Edc[Consumer EDC] -- "request via get/post http" --> Provider_Edc[Provider EDC] + Provider_Edc -- "request via get/post http" --> DTR[Digital Digital Twin Registry] + DTR -- "request via http" --> Provider_Edc + Provider_App[Provider App] -- "request via get/post http" --> DTR + Keycloak -- "administrates the authorization token" <--> DTR + Provider_Edc -- "request via http" --> Consumer_Edc +``` + +| Neighbor | Description | +|------------------|--------------------------------------------------------------------------| +| Consumer EDC | Request for shells to provider EDC | +| Provider EDC | Request for shells to Digital twin Registry | +| Keycloak | Generates token for users and provides id management of user and service | +| Provider App | Requests for create/delete shells | + + +### 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-digital-twin-registry.git \ No newline at end of file diff --git a/docs/architecture/4-runtime-view.md b/docs/architecture/4-runtime-view.md new file mode 100644 index 00000000..96defa3a --- /dev/null +++ b/docs/architecture/4-runtime-view.md @@ -0,0 +1,185 @@ +## 4 Runtime-view + +### Actors and interaction diagrams +There are two actors who interact with the AAS Registry. + +| Actor | Description | Examples | +|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| +| Data provider | The data provider runs its own Digital Twin Registry and registers AAS Descriptors and Submodel Descriptors so that consumers can query for AAS Descriptors and request data via the Submodel Descriptor Endpoints. Responsibilities: Run own Digital Twin Registry, providing EDC compatible Submodel Descriptor Endpoints, Registration of the AAS Descriptors | Any manufacturer who provides data for their assets and runs its own DTR | +| Data consumer | The data consumers are accessing the AAS Registry to discover and consume data from the Submodel Descriptor Endpoints. Responsibilities: Query the AAS Registry for AAS Descriptors, Access the Submodel Descriptor Endpoints via EDC | | + + +The interactions of both actors are shown in the diagrams below. +For the purpose of simplifying, the interactions via EDC is not shown completely. + +EDC is involved as following: +1. As a Data Provider to interact with the DTR there is no EDC needed. +2. As a Data Consumer for interactions the EDC is needed. +3. Interactions with Submodel Endpoints (Data Provider) have to be done with EDC + +### Data provider +To be able to register a DigitalTwin the following prerequisites must be met. +1. The identifiers for an asset are known (specificAssetIds, e.g. serial number, part id) +2. An endpoint that provides the data for the asset is available. The data has to be compliant with an Aspect Model. +3. To register a twin no EDC is needed. But the DTR is secured by an IDM system, so to register a technical user is needed. + +#### Register Twins (simplified without token management by IDM) + +```mermaid +sequenceDiagram + Client->>+Decentralized digital Twin registry: POST /api/v3/shell-descriptors + Decentralized digital Twin registry->>+Client: 200 Ok Response success + Note left of Client: Registers the AAS Descriptor by providing
- assetIds to make discovery possible (e.g. VIN)
- Submodel Descriptor Endpoint +``` + +### Data Provider + +#### Prerequisites +The Digital Twin Registry have to be accessed through an EDC. Following objects are needed to access the registry: + +***1. Create Data Asset*** +The EDC Data Assets represents the location of the Digital Twin Registry offered by the provider. + +| API method | URL: /management/v3/assets (POST) | +|----------------|----------------------------------------------------------| +| **Parameters** | none | +| **Payload** | see below | +| **Returns** | 200 / OK | + +***Data Asset*** + +_note:_ that the "asset:prop:type" is standardized with "data.core.digitalTwinRegistry" for the Digital Twin Registry. + +``` +{ + "@context":{}, + "@id":"{{ASSET_ID}}", + "properties":{ + "dct:type":{ + "@id":"cx-taxo:DigitalTwinRegistry" + } + }, + "dataAddress":{ + "@type":"DataAddress", + "type":"HttpData", + "baseUrl":"{{BACKEND_SERVICE}}", + "proxyPath":"true", + "proxyBody":"true", + "proxyMethod":"true", + "proxyQueryParams":"true", + "oauth2:clientId":"{{REGISTRY_CLIENT_ID}}", + "oauth2:clientSecretKey":"{{REGISTRY_CLIENT_SECRET_KEY}}", + "oauth2:tokenUrl":"{{REGISTRY_TOKEN_ENDPOINT}}", + "oauth2:scope":"{{REGISTRY_TOKEN_SCOPE}}" + } +} +``` + +***2. Create Policy*** + +The policy is the BPN policy to give the consumer access to the asset. + +| API method | URL: /management/v2/policydefinitions (POST) | + |----------------|---------------------------------------------------| +| **Parameters** | none | +| **Payload** | see below | +| **Returns** | 200 / OK | + +***EDC Policy*** + +``` +{ + "@context": [ + "https://w3id.org/tractusx/edc/v0.0.1", + "http://www.w3.org/ns/odrl.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@type": "PolicyDefinition", + "@id": "{{POLICY_ID}}", + "policy": { + "@type": "Policy", + "permission" : [{ + "action" : "USE", + "constraint" : { + "@type": "LogicalConstraint", + "or" : [{ + "@type" : "Constraint", + "leftOperand" : "BusinessPartnerNumber", + "operator" : { + "@id": "odrl:eq" + }, + "rightOperand" : "{{CONSUMER_BPN}}" + }] + } + }] + } +} +``` + +***3. Create Contract Definition*** + +The contract definition links the created policy with the created asset. + +| API method | URL: /management/v2/contractdefinitions (POST) | + |----------------|--------------------------------------------------------------| +| **Parameters** | none | +| **Payload** | see below | +| **Returns** | 200 / OK | + + +***Contract Definition*** + +``` +{ + "@context": {}, + "@type": "ContractDefinition", + "accessPolicyId": "{{dtrSourcePolicyId}}", + "contractPolicyId": "{{dtrSourcePolicyId}}", + "assetsSelector" : { + "@type" : "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "{{dtrSourceAssetId}}" + } +} +``` + +***4. Negotiation*** + +At last both EDCs do the final negotiation and the consumer EDC receives the edr token to get access to the Digital Twin Registry. + + +#### Search for Twins (simplified) +```mermaid +sequenceDiagram + participant Service + participant ConsumerEDC as Consumer EDC + participant ProviderEDC as Provider EDC + participant DecentralDigitalTwinRegistry as Decentral Digital Twin Registry + + Service->>+ConsumerEDC: GET EDR Token + ConsumerEDC->+ProviderEDC: EDC Negotiations + ConsumerEDC-->>-Service: EDR Token + Service->>+ProviderEDC: GET lookup/shells/assetIds + ProviderEDC->>+DecentralDigitalTwinRegistry: GET lookup/shells/assetIds + DecentralDigitalTwinRegistry-->>-ProviderEDC: AssetAdministrationShellIds + ProviderEDC-->>-Service: AssetAdministrationShellIds + Service->>+ProviderEDC: GET /shell-descriptors/{aasIdentifier} + ProviderEDC->>+DecentralDigitalTwinRegistry: GET /shell-descriptors/{aasIdentifier} + DecentralDigitalTwinRegistry-->>-ProviderEDC: AssetAdministrationShellDescriptor + ProviderEDC-->>-Service: AssetAdministrationShellDescriptor + Service->>Service: Extract Endpoint + Service->>ProviderEDC: Get Endpoint (from Submodel Descriptor) + ProviderEDC-->>-Service: Endpoint +``` + +### 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: 2024 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-digital-twin-registry.git \ No newline at end of file diff --git a/docs/architecture/5-deployment-view.md b/docs/architecture/5-deployment-view.md new file mode 100644 index 00000000..93d9c8af --- /dev/null +++ b/docs/architecture/5-deployment-view.md @@ -0,0 +1,19 @@ +## 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/registry". +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](../../README.md) and [install.md](../../INSTALL.md). + +### 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: 2024 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-digital-twin-registry.git \ No newline at end of file diff --git a/docs/architecture/6-crosscutting-concepts.md b/docs/architecture/6-crosscutting-concepts.md new file mode 100644 index 00000000..cda6f28c --- /dev/null +++ b/docs/architecture/6-crosscutting-concepts.md @@ -0,0 +1,515 @@ +## 6 Crosscutting Concept + +### Overall Concept + +The overall concept can be found under **2 Architecture and constraints**. + +### Asset Administration Shell specification +The Digital Twin Registry has implemented Asset Administration Shell specification in version 3.0. +The corresponding openapi file can be found here: [AAS OPENAPI](../../backend/src/main/resources/static/aas-registry-openapi.yaml) + +### Uniqueness +The following table contains the identifier fields and whether they are globally unique, unique for an +AAS Descriptor or not unique at all. + +| Field | Unique globally | Explanation | +|----------------------------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| AssetAdministrationShellDescriptor#id | yes | - | +| AssetAdministrationShellDescriptor#specificAssetIds#key | - | The specificAssetIds are primarily used for searches. There are use cases where multiple values for the same key can exist. For instance, an OEM can have multiple World Manufacturer Identifier (WMI). Queries against any of the WMI must be possible as data consumers may know only one of the WMI. | +| AssetAdministrationShellDescriptor#submodelDescriptor#id | yes | - | + +Uniqueness for natural keys e.g. serial numbers is not given in the manufacturing world. +Therefore, the AAS Registry cannot enforce uniqueness for natural keys (specificAssetIds). + +### Identifiers + +#### Identification and globalAssetId + +| Field | Value | Description | +|-----------------------------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| AssetAdministrationShellDescriptor#id | Random UUIDv4 | - | +| AssetAdministrationShellDescriptor#globalAssetId[0] | Random UUIDv4 | The globalAssetId is a natural key that identifies an asset uniquely. An example for instance is the MAC - Address. In the manufacturing industry not all assets do have a global unique natural key. It was decided therefore to use a random UUID. | +| SubmodelDescriptor#id | Random UUIDv4 | - | + + +### Predefined specificAssetIds +The `specificAssetIds` are collection key-value pairs and the fundamental part for discovery capabilities of the AAS Registry. Data consumers use these specificAssetIds to find AAS Descriptors. +In multiple discussions with different Product Owners and architects, the keys for `specificAssetIds` were defined. +The AAS Registry does not enforce any `specificAssetId key`. However, data providers should use one of these keys if the Asset Administration Shell Descriptor does match one of the defined types e.g. Serial Part, Vehicle. +If you do not find a matching `specificAssetId` key for your use case please contact us so that we can extend the list. + +### Submodel Descriptor Endpoints +The Submodel Descriptor contains all the required information to obtain data from a remote address. +The endpoint for a Submodel Descriptor must be setup as follows: + +| Property | Description | Example Value | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| interface | The type of the endpoint. Only "EDC" is currently supported. | EDC | +| semanticId | The urn of the Semantic Model that describes the data of this endpoint. | urn:bamm:com.catenax:1.0.0#ExampleModel | +| protocolInformation#href | The EDC compatible endpoint where the semanticId compatible data can be fetched. Catena-X defined the URL structure as: Read Endpoint: http:////-/submodel?content=value Operations Endpoint: /invoke?content=value | Read Endpoint: http://myawesomeconnector.com/BPNL7588787849VQ/urn%3Auuid%3Ac227a880-b82b-40f7-846c-3942ddf26c29-urn%3Auuid%3A53125dc3-5e6f-4f4b-838d-447432b97918/submodel?content=value&extent=WithBLOBValue | +| Operation Endpoint: http://myawesomeconnector.com/BPNL7588787849VQ/urn%3Auuid%3Ac227a880-b82b-40f7-846c-3942ddf26c29-urn%3Auuid%3A53125dc3-5e6f-4f4b-838d-447432b97918/submodel/vin-van-converter/invoke?content=value | | | +| protocolInformation#endpointProtocol | The protocol of the endpoint. | HTTPS | +| protocolInformation#endpointProtocolVersion | The version of the protocol. | 1.0 | + +### Authentication & Authorization +The AAS Registry needs to be integrated with an OAuth2 compliant authorization server. Every API call has to provide a valid Bearer Token issued by this authorization server. +Authorization is supported by Role Based Access Control (RBAC). Following roles are available: + +| Role | Description | +|-------------------------|----------------------------------------------------------| +| view_digital_twin | Can read all digital twins. | +| add_digital_twin | Can add a digital twin. | +| update_digital_twin | Can update a digital twin. | +| delete_digital_twin | Can delete a digital twin. | +| submodel_access_control | Can perform submodel access control authorization calls. | +| read_access_rules | Can read the rules defined for access control. | +| write_access_rules | Can write the rules defined for access control. | + +Depending on being a Data Provider or a Data Consumer there are different tokens for authentication and authorization needed. +#### Data Provider +1. technical user for the service which administrates the Digital Twin Registry +2. technical user for the EDC which makes the requests in behalf of the Data Consumer to the DTR. + +#### Data Consumer +1. needs an EDR token which is provided between the intercommunication between the EDCs. + +#### AWS Cognito as Identity Provider +DTR can support Keycloak and AWS Cognito as an Identity Provider for all clients that want to access the registry. +Client must fetch a token and send it together with the request. +Cognito behaves somehow different than Keycloak so some code modifications were necessary to use Cognito as an Identity Provider for DTR. +Detailed information can be found [here](COGNITO.md) + +### Authentication on behalf of a user +The AAS Registry can be accessed on behalf of a user. The token has to be obtained via the OpenID Connect flow. The AAS Registry will validate these tokens. +*Support contact* tractusx-dev@eclipse.org + +### Access control to Digital Twins Based on the BPN (Business Partner Number)/ TenantId + +#### Classic implementation + +The visibility of `specificAssetIds` in the Digital Twin Registry based on the Business Partner Number (BPN) (Which is send via header Edc-Bpn) can be controlled with the attribute `externalSubjectId`. Hence, the `externalSubjectId` is identified with the BPN. +The communication between consumer and provider is via EDC. Before the provider EDC sends the request to the DTR, the property Edc-Bpn with the BPN of the consumer will be set by the provider EDC. + + +* The BPN as attribute to a *specificAssetId* can be optionally provided in `specificAssetIds`. This can be done with `externalSubjectId`. +* Only those users, where `externalSubjectId` matches the Eclipse Dataspace Components-Header (Edc-Bpn -> *i.e.* BPN) are able to discover and read exactly this content of `specificAssetIds`. +* The behavior is **closed by default**, *i.e.*, if no `externalSubjectId` is defined to a `specificAssetId`, the content of this particular `specificAssetId` (key, value) is only visible for the owner of the *Digital Twin* (also known as data provider). +* To mark a `specificAssetId` as public for every reader on a *Digital Twin*, the defined characters (`"PUBLIC_READABLE"`) need to be added in the `externalSubjectId`. + * *Cave: The publisher of `specificAssetIds` needs to consider antitrust law. This use of `"PUBLIC_READABLE"` is only allowed for the *specificAssetId* `"assetLifecyclePhase"` and `"manufacturerPartId"` (which is technically enforced by the Digital Twin Registry) if its content describes material numbers of products and those products are or were in serial production for the open market. If its content describes material numbers of products in state of, *e.g.*, pre-production, being planned for production, being unsold, the use of `"PUBLIC_READABLE"` is not allowed and use of dedicated read access via `externalSubjectId` is to be used instead. `"manufacturerPartId"` is not allowed to be used for different content than the one described here.* +* The behavior of the Digital Twin Registry is as follows. The read-access from `specificAssetIds` is inherited by the other fields of a *Digital Twin*. + * An owner and a user with respect to the BPN, who has read-access to one of the `specificAssetIds` (`externalSubjectId` has `"value":""`) has read-access to the other fields of a *Digital Twin* as well, *i.e.* (see the full list of fields [POST Asset Administration Shell Descriptor v3.0 SSP-001](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.0_SSP-001#/Asset%20Administration%20Shell%20Registry%20API/PostAssetAdministrationShellDescriptor)) + * `description` + * `displayName` + * `administration` + * `assetKind` + * `assetType` + * `globalAssetId` + * `idShort` + * `id` + * `submodelDescriptors` + * `specificAssetIds` + + * A user, who has only general read-access to `specificAssetIds` (`externalSubjectId` has `"value":"PUBLIC_READABLE"`) has only read-access to the following fields of a *Digital Twin* + * `id` + * `submodelDescriptors` + * `specificAssetIds` + * The list of `keys` in the externalSubjectId is filtered for the requested user. Only the keys will be returned where the BPN matched. + +**Hint**
+The defined string for `"PUBLIC_READABLE"` and the list of allowed types to mark as public is configurable via helm values.yml: +* `registry.externalSubjectIdWildcardPrefix` (Default is `"PUBLIC_READABLE"` ) +* `registry.externalSubjectIdWildcardAllowedTypes` (Default is `"manufacturerPartId,assetLifecyclePhase"` ) + +Detailed information can be found [here](../INSTALL.md) +_________________ + + + +Example to create a *Digital Twin* with `specificAssetIds`: +``` +POST Method: +{{registry-baseurl}}/api/v3/shell-descriptors +``` + +```json +POST Body (JSON): +{ + "idShort":"idShortExample", + "id":"e1eba3d7-91f0-4dac-a730-eaa1d35e035c-2", + "description":[ + { + "language":"en", + "text":"Example of human readable description of digital twin." + } + ], + "specificAssetIds":[ + { + "name":"partInstanceId", + "value":"24975539203421" + }, + { + "name":"customerPartId", + "value":"231982", + "externalSubjectId":{ + "type":"ExternalReference", + "keys":[ + { + "type":"GlobalReference", + "value":"BPN_COMPANY_001" + } + ] + } + }, + { + "name":"manufacturerId", + "value":"123829238", + "externalSubjectId":{ + "type":"ExternalReference", + "keys":[ + { + "type":"GlobalReference", + "value":"BPN_COMPANY_001" + }, + { + "type":"GlobalReference", + "value":"BPN_COMPANY_002" + } + ] + } + }, + { + "name":"manufacturerPartId", + "value":"231982", + "externalSubjectId":{ + "type":"ExternalReference", + "keys":[ + { + "type":"GlobalReference", + "value":"PUBLIC_READABLE" + } + ] + } + } + ], + "submodelDescriptors":[ + { + "endpoints":[ + { + "interface":"SUBMODEL-3.0", + "protocolInformation":{ + "href":"https://edc.data.plane/mypath/submodel", + "endpointProtocol":"HTTP", + "endpointProtocolVersion":[ + "1.1" + ], + "subprotocol":"DSP", + "subprotocolBody":"body with information required by subprotocol", + "subprotocolBodyEncoding":"plain", + "securityAttributes":[ + { + "type":"NONE", + "key": "NONE", + "value": "NONE" + } + ] + } + } + ], + "idShort":"idShortExample", + "id":"cd47615b-daf3-4036-8670-d2f89349d388-2", + "semanticId":{ + "type":"ExternalReference", + "keys":[ + { + "type":"Submodel", + "value":"urn:bamm:io.catenax.serial_part_typization:1.1.0#SerialPartTypization" + } + ] + }, + "description":[ + { + "language":"de", + "text":"Beispiel einer lesbaren Beschreibung des Submodels." + }, + { + "language":"en", + "text":"Example of human readable description of submodel" + } + ] + } + ] +} +``` +This example is a *Digital Twin* with four different `specificAssetIds` as descriptors. +* `partInstanceID` is discoverable and visible only for the owner of the *Digital Twin*, since no `externalSubjectId` is defined. +* `customerPartId` is discoverable and visible only for the owner of the *Digital Twin* and an (external) reader via EDC, who has the bpn-value "BPN_COMPANY_001" in the header of the EDC +* `manufacturerId` is discoverable and visible only for the owner of the *Digital Twin* and two (external) readers via EDC, who have the bpn-value "BPN_COMPANY_001" and "BPN_COMPANY_002" in the header of the EDC +* `manufacturerPartId` is discoverable and visible for everyone, who has access to the Digital Twin Registry, because the `externalSubjectId` has the value `"PUBLIC_READABLE"` included. + +For example, if an (external) reader via EDC requests the here shown *Digital Twin* and the edc-bpn header includes the bpn-value "BPN_COMPANY_001", the list of `specificAssetIds` contains three entries, namely: +* `customerPartId` +* `manufacturerId` +* `manufacturerPartId` + +In consequence, the reader "BPN_COMPANY_001", as well as the reader "BPN_COMPANY_002" and the owner of this *Digital Twin* has full read access to the other fields of this *Digital Twin*, *i.e.* `idShort`, `id`, `description`, and `submodelDescriptors`. + +In this example, the `specificAssetId` `"name": "partInstanceId"` is filtered out, because it is only visible for the owner of the *Digital Twin*. + +Any (external) readers with respect to the `"PUBLIC_READABLE"` flag at `specificAssetId` `"name": "manufacturerPartId"`, have access to the fields +* `id` +* `submodelDescriptors` + +of this *Digital Twin*. + +#### Granular access control implementation + +The granular access control implementation is provided as an alternative option to enforce visibility rules of the *Digital Twin* details. These can be: + +1. The visibility of the *Digital Twin* as a whole +2. The visibility of certain `specificAssetId` names and values of the *Digital Twin* +3. The visibility of certain `submodelDescriptors` of the *Digital Twin* +4. Restricting access to *Digital Twin* details which are `"PUBLIC_READABLE"` + (only showing the `id`, the public readable `specificAssetId` names and values, the `createdDate` and the filtered `submodelDescriptors` ) + +> [!NOTE] +> We have created an EDC extension to let you leverage the benefits of granular access control to the full extent. Please read the related details [here](EDC-extension-configuration.md)! + +##### Configuring granular access control + +To enable granular access control (instead of the classic implementation), the `registry.useGranularAccessControl` configuration HELM chart property must be set to `"true"`. +This will in turn set `registry.use-granular-access-control` Spring property to `true`, which will activate the granular access control. + +In addition to the aforementioned property, we can set the number of records fetched when listing records. This can be done by setting the +`registry.granularAccessControlFetchSize` HELM chart property. The default value is `"500"`. Providing this property will set the `registry.granular-access-control-fetch-size` +Spring property of the Digital Twin Registry to the equivalent int value. In general, the higher we can set this value, the fewer fetches will be required when shells are +listed and filtered. It is recommended to use at least 1000 if the registry has more than 100 000 Digital Twins. + +##### Creating an access rule + +The access rules can be managed using the provided access rule API ([See API specs here](../access-control-service-sql-impl/src/main/resources/static/access-control-openapi.yaml)). + +> [!NOTE] +> In order to use the API, the client must have the `read_access_rules` and `write_access_rules` roles. + +Please refer to the following table to get familiar with the schema of the access rules. + +| Property | Type | Required on create | Description | +|-------------|----------|--------------------|----------------------------------------------------------------------------------------| +| id | long | No (read-only) | The auto-incremented Id of the rule. | +| tid | string | No (read-only) | The Id of the owner tenant (the owner of the Digital Twin Registry). | +| policyType | enum | Yes | Defines the policy language used for the rule's policy. Possible values: `AAS`. | +| policy | json | Yes | The definition of the access rule. | +| description | string | No (optional) | An short, optional description or note to help with the maintenance of the rule. | +| validFrom | datetime | No (optional) | An optional timestamp representing the earlier time when the rule should be in effect. | +| validTo | datetime | No (optional) | An optional timestamp representing the latest time when the rule should be in effect. | + +An example policy: + +```json +{ + "id": 1, + "tid": "00000000-1111-2222-3333-444444444444", + "policyType": "AAS", + "policy": { + "accessRules": [ + { + "attribute": "bpn", + "operator": "eq", + "value": "BPNL00000000000A" + }, + { + "attribute": "mandatorySpecificAssetIds", + "operator": "includes", + "values": [ + { + "attribute": "manufacturerPartId", + "operator": "eq", + "value": "99991" + }, + { + "attribute": "customerPartId", + "operator": "eq", + "value": "ACME001" + } + ] + }, + { + "attribute": "visibleSpecificAssetIdNames", + "operator": "includes", + "values": [ + { + "attribute": "name", + "operator": "eq", + "value": "manufacturerPartId" + }, + { + "attribute": "name", + "operator": "eq", + "value": "customerPartId" + }, + { + "attribute": "name", + "operator": "eq", + "value": "partInstanceId" + } + ] + }, + { + "attribute": "visibleSemanticIds", + "operator": "includes", + "values": [ + { + "attribute": "modelUrn", + "operator": "eq", + "value": "Traceabilityv1.1.0" + }, + { + "attribute": "modelUrn", + "operator": "eq", + "value": "ProductCarbonFootprintv1.1.0" + } + ] + } + ] + }, + "description": "Access rule description.", + "validFrom": "2024-01-02T03:04:05Z", + "validTo": "2024-06-07T08:09:10Z" +} +``` + +The example policy above can be split into multiple parts when read. + +1. Validity - It is valid between `2024-01-02T03:04:05Z` and `2024-06-07T08:09:10Z`. Otherwise, it is ignored. +2. Scope - Outlining when a rule is applicable. + 1. The first access rule (`$.policy.accessRules[0]`) defines the *bpn* (*externalSubjectId*) of the tenant to whom the policy applies. + 2. The second access rule (`$.policy.accessRules[1]`) defines the *mandatorySpecificAssetIds* which must be present in the *Digital Twin* in order for the rule to be applicable. The rule will become applicable only if __all__ *specificAssetId* name-value pairs of the rule are present in the *Digital Twin*. +3. Effect - Defines which parts of the matching *Digital Twins* should be visible when the client's *externalSubjectId* matches the rule's. + 1. The third access rule (`$.policy.accessRules[2]`) defines the *visibleSpecificAssetIdNames*. When the rule matches, the *specificAssetIds* from the + *Digital Twin* with these names should be visible using one of the cases below: + 1. When the same name is present as a name in the *mandatorySpecificAssetIds* and the *visibleSpecificAssetIdNames*, then the rule will only make a + *specificAssetId* from the *Digital Twin* when the *specificAssetId* is listed as an item of the *mandatorySpecificAssetIds*. + 2. Otherwise, if the name is only present as a *visibleSpecificAssetIdNames* without being present on the *mandatorySpecificAssetIds* as well, the rule + will make visible any *specificAssetId* from the *Digital Twin* if the name of the *specificAssetId* matches the name from the *visibleSpecificAssetIdNames*, + regardless of the value of the *specificAssetId* in the *Digital Twin*. + 2. The fourth access rule (`$.policy.accessRules[3]`) defines the *visibleSemanticIds*. These *semanticIds* are identifying the *submodelDescriptors* from the *Digital Twin* which should be visible when the rule matches. + +##### How the rule evaluation works? + +In general, when a shell's visibility is evaluated, we must: + +1. Take the *externalSubjectId* of the client, the *ownerTenantId* of the *Digital Twin Registry* and the contents of the *Digital Twin* in question. +2. If the *externalSubjectId* is equal to the *ownerTenantId*, the client can see the full content. +3. Otherwise, we must fetch all access rules which belong to the client's *externalSubjectId* or `PUBLIC_READABLE`; and is in the specified validity period +4. Then, for each *specificAssetId* of the *Digital Twin*, we must verify whether there is at least one applicable rule that gives access to the *specificAssetId* of the *Digital Twin*. +5. Similarly, for each *submodelDescriptor* of the *Digital Twin*, we must verify whether there is at least one applicable rule that gives access to the *semanticId* of the *submodelDescriptor* from the *Digital Twin*. + +The process acn be summed up in a more visual way as shown in the diagram below: + +```mermaid +flowchart LR + START + START-->isAdmin{Is\nexternalSubjectId\n=\nownerTenantId?} + isAdmin-- no -->fetchRules[Fetch valid rules\nfor externalSubjectId\nor PUBLIC_READABLE] + isAdmin-- yes -->showAll[Show full content] + fetchRules-->anyRules{Any rules found?} + anyRules-- yes -->startForEach((For each rule)) + startForEach-->isRuleMatching{Is the\nrule matching\nthe Digital Twin?} + isRuleMatching-- no -->endForEach((For each rule)) + isRuleMatching-- yes -->applyRule[Apply rule effect] + applyRule-->endForEach + endForEach-->isShellVisible{Is the\nDigital Twin\nvisible?} + isShellVisible-- yes -->showFiltered[Show filtered Digital Twin] + isShellVisible-- no -->denied[Hide Digital Twin] + anyRules-- no -->denied + showAll-->END + denied-->END + showFiltered-->END +``` + +###### Lookup shells - `GET {{baseUrl}}/api/v3/lookup/shells?assetIds=...` + +In case of the lookup shells, the filtering and access control of the *Digital Twins* is done using the following steps: + +1. A page (fetchSize) of *Digital Twins* is loaded which are matching the client's query expression. +2. The list of shells fetched in the previous step is filtered by applying the access control rules to them one-by-one. +3. The process is repeated until we have the desired number of *Digital Twins* or there are no more *Digital Twins* to fetch. +4. The AAS Ids of the visible *Digital Twins* are returned. + +###### Get all shells - `GET {{baseUrl}}/api/v3/shell-descriptors` + +The process is similar to the lookup shells, the filtering and access control of the *Digital Twins* is done as follows: + +1. A page (fetchSize) of *Digital Twins* is loaded. +2. The list of shells fetched in the previous step is filtered by applying the access control rules to them one-by-one. +3. The process is repeated until we have the desired number of *Digital Twins* or there are no more *Digital Twins* to fetch. +4. The visible properties of the visible *Digital Twins* are returned. + 1. If the list of *specificAssetIds* in the shell has *multiple* entries with the same name, then the following rules apply: + 1. Usecase 1: A rule includes a specificAssetId (for example customerPartId=123) as *mandatorySpecificAssetId and visibleSpecificAssetId*. The Shell has multiple entries with the same name and *one of the entry* matched the value from mandatorySpecificAssetId, then only the matched entry is visible. + 2. Usecase 2: A rule includes a specificAssetId (for example customerPartId=123) as *mandatorySpecificAssetId and visibleSpecificAssetId*. The Shell has multiple entries with the same name and *none of the entries* matched the value from mandatorySpecificAssetId, then no entries with the same name is visible. + +###### Get Shell by AAS Id - `GET {{baseUrl}}/api/v3/shell-descriptors/:aasIdentifier` + +To determine the visibility of a single *Digital Twin*, we can simply: + +1. Fetch the *Digital Twin* +2. Apply the access control rules using the process defined at the beginning of this section +3. Return the visible parts of the *Digital Twin* (or empty result in case the *Digital Twin* is not visible at all) + +#### Public readable + +When a *Digital Twin* is only visible because there are applicable `PUBLIC_READABLE` rules which make certain properties visible, +the shell details are further limited. This means, that we are returning only: + +- the `id`, +- the `idEsternal` (*AAS Id*), +- the public readable `specificAssetId` names and values, +- the `createdDate` +- the filtered `submodelDescriptors` + +### Security Assessment + +Data flow diagram: + +```mermaid +%%{init: {"flowchart": {"curve": "linear"} }}%% +graph TB + CD[Consumer Data] + CE[Consumer EDC] + PE[Provider EDC] + DP[Data Provider] + IDM[IDM] + DTR-B[DTR Backend] + DTR-P[DTR Postgres] + + subgraph Provider Env + PE + DP + IDM + subgraph Digital Twin Registry + DTR-B + DTR-P + end + end + + CD <-->|X-API auth key \n return twin| CE + CE <-->|EDC flow \n certificate based auth \n provide role| PE + + PE -->|Get token| IDM + DP -->|Get token| IDM + DTR-B -->|Get public key \n token validation| IDM + + PE <-->|Get twin & submodel| DTR-B + DP <-->|Register twin & submodel| DTR-B + DTR-B <-->|Create twin & submodel| DTR-P +``` + + +### 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: 2024 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-digital-twin-registry.git \ No newline at end of file diff --git a/docs/architecture/7-quality-scenarios.md b/docs/architecture/7-quality-scenarios.md new file mode 100644 index 00000000..01db54cc --- /dev/null +++ b/docs/architecture/7-quality-scenarios.md @@ -0,0 +1,18 @@ +## 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/) | + +### 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: 2024 Robert Bosch Manufacturing Solutions GmbH +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/sldt-digital-twin-registry.git \ No newline at end of file diff --git a/docs/architecture/glossary.md b/docs/architecture/glossary.md new file mode 100644 index 00000000..f4797625 --- /dev/null +++ b/docs/architecture/glossary.md @@ -0,0 +1,19 @@ +## Glossary + +| Term | Description | +|---------------|----------------------------------------------------------------------------------------------------------------| +| EDC | Eclipse Data Space Connector | +| DTR | Digital Twin Registry - the phone book to register and to search for endpoints for Digital Twins | +| dDTR | decentralized Digital Twin Registry - the Digital Twin Registry which is deployed on each Data Provider system | +| Data Provider | deploys a own Digital Twin Registry and provides the data for his digital twins | +| Data Consumer | uses the Digital Twin Registry to search for digital twins | +| IDM | User identity management e.g. Keycloak | + +### 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-digital-twin-registry.git \ No newline at end of file diff --git a/docs/img/decentralEnviroment.PNG b/docs/architecture/media/decentralEnviroment.PNG similarity index 100% rename from docs/img/decentralEnviroment.PNG rename to docs/architecture/media/decentralEnviroment.PNG diff --git a/docs/COGNITO.md b/docs/guideline-aws-cognito-configuration.md similarity index 99% rename from docs/COGNITO.md rename to docs/guideline-aws-cognito-configuration.md index ce927b1b..bab7851a 100755 --- a/docs/COGNITO.md +++ b/docs/guideline-aws-cognito-configuration.md @@ -1,4 +1,4 @@ -# AWS Cognito as Identity Provider +# Guideline to use AWS Cognito as Identity Provider DTR can support Keycloak and AWS Cognito as an Identity Provider for all clients that want to access the registry. Client must fetch a token and send it together with the request. Cognito behaves somehow different than Keycloak so some code modifications were necessary to use Cognito as an Identity Provider for DTR. diff --git a/docs/EDC-extension-configuration.md b/docs/guideline-edc-extension-configuration.md similarity index 99% rename from docs/EDC-extension-configuration.md rename to docs/guideline-edc-extension-configuration.md index 7c52a2ed..06db5ec2 100644 --- a/docs/EDC-extension-configuration.md +++ b/docs/guideline-edc-extension-configuration.md @@ -1,4 +1,4 @@ -# Digital Twin Registry Data Plane HTTP Access Control Eclipse Dataspace Connector extension +# Guideline Digital Twin Registry Data Plane HTTP Access Control Eclipse Dataspace Connector extension ## 1 Introduction and goals