Skip to content

Commit

Permalink
Add documentation for access control of shells
Browse files Browse the repository at this point in the history
  • Loading branch information
@tunacicek
tunacicek committed Aug 23, 2023
1 parent b26e331 commit 0574f40
Showing 1 changed file with 170 additions and 77 deletions.
247 changes: 170 additions & 77 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -420,93 +420,186 @@ Depending on being a Data Provider or a Data Consumer there are different tokens
#### Data Consumer
1. needs an EDR token which is provided between the intercommunication between the EDCs.

### 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.

#### Postman configuration
![](img/image005.png)

*Support contact* tractusx-dev@eclipse.org

### Access control to Digital Twins Based on the BPN (Business Partner Number)/ TenantId
The visibility of `specificAssetIds` in the Digital Twin Registry based on the Business Partner Number (BPN) can be controlled with the attribute `externalSubjectId`. Hence, the `externalSubjectId` is identified with the BPN.

* 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 (*i.e.* BPN) are able to discover via 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"` (only `"value":"AsBuilt"`, and `"value":"AsPlanned"` allowed; see [Eclipse Tractus-X - Traceability Kit](https://eclipse-tractusx.github.io/docs-kits/next/kits/Traceability%20Kit/Software%20Development%20View/Specification%20Traceability%20Kit)), 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":"<Business Partner Number>"`) 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`
* `extensions`
* `administration`
* `assetKind`
* `assetType`
* `endpoints`
* `globalAssetId`
* `idShort`
* `id`
* `submodelDescriptors`

#### Visibility of specificAssetIds based on tenantId/BPN
You can control the visibility of specificAssetIds based on the tenantId/BPN.
- You can provide the tenantId/BPN as attribute to a specificAssetId. Only users having the same tenantId/BPN in the Header (property: Edc-Bpn) are able to see the specificAssetId.
- 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 specificAssetIds of Digital Twins you created will always be shown to you.
* A user, who has <u>only</u> general read-access to `specificAssetIds` (`externalSubjectId` has `"value":"PUBLIC_READABLE"`) has <u>only</u> read-access to the following fields of a *Digital Twin*
* `id`
* `submodelDescriptors`

Detailed example:
**Hint** <br>
The defined character 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`:
```
// Given specificAssetIds:
"specificAssetIds": [
{
"externalSubjectId": {
"type": "ExternalReference",
"keys": [
{
"type": "GlobalReference",
"value": "BPN12"
}
]
},
"name": "CustomerPartId",
"value": "293913"
},
{
"externalSubjectId": {
"type": "ExternalReference",
"keys": [
{
"type": "GlobalReference",
"value": "BPN49"
}
]
POST Method:
{{registry-baseurl}}/api/v3.0/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": "429212"
},
{
"externalSubjectId": {
"type": "ExternalReference",
"keys": [
{
"type": "GlobalReference",
"value": "BPN29"
}
]
{
"name":"customerPartId",
"value":"231982",
"externalSubjectId":{
"type":"ExternalReference",
"keys":[
{
"type":"GlobalReference",
"value":"BPN_COMPANY_001"
}
]
}
},
"name": "CustomerPartId",
"value": "523192"
}
]
// A customer with (BPN12) will only get the specificAssetIds that contains his BPN/tenantId. Taking the above example, the response for the customer //(BPN12) would be:
[
{
"externalSubjectId": {
"type": "ExternalReference",
"keys": [
{
"type": "GlobalReference",
"value": "BPN12"
}
]
{
"name":"manufacturerId",
"value":"123829238",
"externalSubjectId":{
"type":"ExternalReference",
"keys":[
{
"type":"GlobalReference",
"value":"BPN_COMPANY_001"
},
{
"type":"GlobalReference",
"value":"BPN_COMPANY_002"
}
]
}
},
"name": "CustomerPartId",
"value": "293913"
},
]
// Lookup API: GET api/v3.0/shells/lookup and POST api/v3.0/shells/lookup/query with BPN12
// REQUEST:
[
{
"key": "CustomerPartId",
"value": "429212" // note: the externalSubjectId of this assetId is BPN49
}
]
// RESPONSE:
// The response is empty, because the above assetId belongs to customer (BPN49) and not to the customer (BPN12).
[]
{
"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 <u>no</u> `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.

### 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.
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`

#### Postman configuration
![](img/image005.png)
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`.

*Support contact* tractusx-dev@eclipse.org
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*.

## 7 Quality scenarios

Expand Down

0 comments on commit 0574f40

Please sign in to comment.