Grant read access to business partners

Within Catena-X, Business Partner Numbers (BPN) allow for sharing data with third parties.

This page details how to manage read access to specific assets of Asset Administration Shell Descriptor entities (Shells) within the Digital Twin Registry.

For accessing the Asset Administration Shells on the data provider’s tenant of the Digital Twin Registry, membership on that tenant is not enough. In addition to just having access to the tenant, the users and the technical clients also need the corresponding roles (AAS Viewer or AAS Manager). For details, refer to Authorization.

Closed by default and accessible only by the owner

By default, only the owner of an Asset Administration Shell Descriptor entity can access it and can see all the Asset Administration Shell Descriptor entity attributes.

Semantic meaning of the `externalSubjectId` attribute

The Digital Twin Registry allows the discovery of an Asset Administration Shell by search via specific asset IDs associated with the asset represented by the Asset Administration Shell. This is done by using the specificAssetIds attribute within the Asset Administration Shell Descriptor. To each such a specific asset ID, assign an externalSubjectId to grant read access. The value of externalSubjectId corresponds to a BPN or `PUBLIC_READABLE `.

Without an externalSubjectId, the content remains exclusively visible to the owner of the Asset Administration Shell.

Example A - Lock access to owner of the Asset Administration Shell

SpecificAssetIds can be posted to existing Asset Administration Shells using the SpecificAssetId registration endpoint

[
   {
      "name": "partInstanceId",
      "value": "24975539203421"
   }
]

In this example, because an externalSubjectId attribute is missing, only you as the owner can access the Asset Administration Shell listed below and its SpecificAssetId.

How read access is facilitated to data consumers

Only users for whom their Business Partner Numbers (BPN) fetched into the Eclipse Dataspace Components header of their API request matches the externalSubjectId of an Asset Administration Shell can discover and read the content that is allowed for their BPN or which is set public readable.

Enabling public readable access

To grant all users read access to a specific asset, include an externalSubjectId. Assign either the manufacturerPartId or assetLifecyclePhase as its name and set the value to PUBLIC_READABLE.

Using PUBLIC_READABLE allows for reading the specificAssetId.name attribute. It works only for the value manufacturerPartId or assetLifecyclePhase. Any other value of specificAssetId.name is considered invalid for enabling the public read access and therefore the public read access feature will not be enabled for that specific asset. However, granting read access to particular BPNs is still possible, as it will be showcased below in section Example C - Grant access to specific BPN.

Example B - Grant public readable access

Using the SpecificAssetId registration endpoint to post SpecificAssetIds to an existing Asset Administration Shell:

[
   {
      "name": "manufacturerPartId",
      "value": "231982",
      "externalSubjectId": {
         "type": "ExternalReference",
         "keys": [
            {
               "type": "GlobalReference",
               "value": "PUBLIC_READABLE"
            }
         ]
      }
   }
]

All readers of this Asset Administration Shell can read the specificAssetId because it is a manufacturerPartId (also works for assetLifecyclePhase) and it has been marked as PUBLIC_READABLE.

Allow read access to particular BPNs

Assign an externalSubjectId to each specific asset of an Asset Administration Shell for which you want to grant read access. In the externalSubjectId you can add the BPN that is allowed to read the specific asset.

This functionality is facilitated by the comparison with the BPN header sent in API requests to the Digital Twin Registry, as described in How read access is facilitated to data consumers.

Example C - Grant access to specific BPN

Below example depicts the scenario of two dedicated business partners who can read this specific Asset Administration Shell. As shown below, the specific Asset Administration Shell has to be defined twice because the externalSubjectId attribute holds one BPN access.

[
   {
      "name": "manufacturerId",
      "value": "123829238",
      "externalSubjectId": {
         "type": "ExternalReference",
         "keys": [
            {
               "type": "GlobalReference",
               "value": "BPN_COMPANY_001"
            }
         ]
      }
   },
   {
      "name": "manufacturerId",
      "value": "123829238",
      "externalSubjectId": {
         "type": "ExternalReference",
         "keys": [
            {
               "type": "GlobalReference",
               "value": "BPN_COMPANY_002"
            }
         ]
      }
   }
]

Secure the list of BPNs having access

The business partners who can discover the existence of an Asset Administration Shell and thus its Asset Administration Shell Descriptor cannot discover which are the other business partners who also may find the same Asset Administration Shell, i.e. which other BPNs are assigned to the specific asset IDs.

Considering above example Example C - Grant access to specific BPN, the business partner "BPN_COMPANY_002" cannot detect that "BPN_COMPANY_001" also may discover the Asset Administration Shell via the specific asset ID manufacturerId with value 123829238, because this information is omitted in the API response that business partner 002 receives. Below example shows how the response looks like for business partner 002:

[
   {
   "name": "manufacturerId",
   "value": "123829238",
   "externalSubjectId": {
      "type": "ExternalReference",
      "keys": [
         {
            "type": "GlobalReference",
            "value": "BPN_COMPANY_002"
         }
         ]
      }
   }
]

Combining the BPN-based and public readable read accesses and securing the read access list

Let’s assume the below scenario, in which the owner of the Asset Administration Shell Descriptor entity wants to grant read access to the Asset Administration Shell Descriptor for the following third parties for specific assets:

Business partner 001
Business partner 002
Business partner 003

In this example the Asset Administration Shell Descriptor entity has four specific asset IDs:

partInstanceId — which is something the owner wants to keep private to themselves
customerPartId — which the owner wants to share with only one business partner
manufacturerId — which the owner wants to share with two business partners
manufacturerPartId — which the owner wants to be always readable for all business partners

In this example, the owner wants to allocate read access as detailed in the following table:

partInstanceId customerPartId manufacturerId manufacturerPartId

	`partInstanceId`	`customerPartId`	`manufacturerId`	`manufacturerPartId`
Business partner 001	—	read access	read access	public readable
Business partner 002	—	—	read access	public readable
Business partner 003	—	—	—	public readable

Business partner 001

—

read access

public readable

Business partner 002

—

read access

public readable

Business partner 003

—

public readable

To achieve read access as indicated in the table, the owner of the Asset Administration Shell Descriptor entity needs to shape the specificAssetIds as follows:

[
   {
   "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"
            }
         ]
      }
   },
   {
   "name": "manufacturerId",
   "value": "123829238",
   "externalSubjectId":
      {
         "type": "ExternalReference",
         "keys": [
            {
               "type": "GlobalReference",
               "value": "BPN_COMPANY_002"
            }
         ]
      }
   },
   {
   "type": "GlobalReference",
   "name": "manufacturerPartId",
   "value": "231982",
   "externalSubjectId":
      {
         "type": "ExternalReference",
         "keys": [
            {
               "type": "GlobalReference",
               "value": "PUBLIC_READABLE"
            }
         ]
      }
   }
]

The following examples detail the response which each user receives when requesting the Asset Administration Shell Descriptor entity. Note that if the Asset Administration Shell Descriptor entity is accessible through a BPN number or a public readable key, then only the id, specificAssetIds, submodelDescriptors and groups attributes are provided.

For clarity, the containment of submodelDescriptors and groups are left empty in all the examples below. However, it is important to note that all the submodel descriptors belonging to the Asset Administration Shell Descriptor entity and all the shell groups to which the Asset Administration Shell Descriptor entity belongs, are shared with the partners.

Example D - Accessing the Asset Administration Shell Descriptor entity as owner

{
   "id":"urn:uuid:123e4567-e89b-12d3-a456-426655440000",
   "idShort":"Sensor_BNPL001000TS123_377-9efa-67gh023",
   "globalAssetId":"urn:uuid:123e4567-e89b-12d3-a456-426655440000",
   "displayName":[
      {
         "language":"de",
         "text":"Sensor fuer Auto"
      },
      {
         "language":"en",
         "text":"Sensor for car"
      }
   ],
   "description":[
      {
         "language":"de",
         "text":"Das ist ein Beispiel."
      },
      {
         "language":"en",
         "text":"this is an example"
      }
   ],
   "assetKind":"Instance",
   "assetType":"urn:uuid:123e4567-e89b-12d3-a456-896655440001",
   "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"
               }
            ]
         }
      },
      {
         "name":"manufacturerId",
         "value":"123829238",
         "externalSubjectId":{
            "type":"ExternalReference",
            "keys":[
               {
                  "type":"GlobalReference",
                  "value":"BPN_COMPANY_002"
               }
            ]
         }
      },
      {
         "type":"GlobalReference",
         "name":"manufacturerPartId",
         "value":"231982",
         "externalSubjectId":{
            "type":"ExternalReference",
            "keys":[
               {
                  "type":"GlobalReference",
                  "value":"PUBLIC_READABLE"
               }
            ]
         }
      }
   ],
   "submodelDescriptors":[
      {
         "id":"sensorEndpoint1",
         "idShort":"exampleSubModelShortId",
         "description":[
            {
               "language":"en",
               "text":"sensor submodel"
            }
         ],
         "endpoints":[
            {
               "interface":"interfaceName",
               "protocolInformation":{
                  "href":"https://edc.data.plane/sensor/submodel",
                  "endpointProtocol": "https",
                  "subprotocol": "DSP",
                  "subprotocolBody": "id=123;dspEndpoint=http://edc.control.plane/",
                  "subprotocolBodyEncoding":"plain",
                  "endpointProtocolVersion":["1.1.0"],
                  "securityAttributes":[
                     {
                        "type":"RFC_TLSA",
                        "key":"key1",
                        "value":"mySecurityValue"
                     }
                  ]
               }
            }
         ],
         "semanticId":{
            "keys":[
               {
                  "value":"abc",
                  "type":"Blob"
               }
            ],
            "value":"urn:samm:net.catenax.vehicle.submodelExample:2.0.0#Parts",
            "type":"ExternalReference"
         }
      }
   ],
   "groups":["sensor_group"],
   "labels":["sensor"]
}

Example E - Accessing the Asset Administration Shell Descriptor entity as "BPN_COMPANY_001" BPN

As shown below, the business partner 001 is not aware about the sharing details with other partners.

{
   "id":"urn:uuid:123e4567-e89b-12d3-a456-426655440000",
   "idShort":"Sensor_BNPL001000TS123_377-9efa-67gh023",
   "globalAssetId":"urn:uuid:123e4567-e89b-12d3-a456-426655440000",
   "displayName":[...],
   "description":[...],
   "assetKind":"Instance",
   "assetType":"urn:uuid:123e4567-e89b-12d3-a456-896655440001",
   "specificAssetIds":[
      {
         "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",
         "name":"manufacturerPartId",
         "value":"231982",
         "externalSubjectId":{
            "type":"ExternalReference",
            "keys":[
               {
                  "type":"GlobalReference",
                  "value":"PUBLIC_READABLE"
               }
            ]
         }
      }
   ],
   "submodelDescriptors":[...],
   "groups":[...],
   "labels":[...]
}

Example F - Accessing the Asset Administration Shell Descriptor entity as "BPN_COMPANY_002" BPN

As shown below, the business partner 002 is not aware about the sharing details with other partners.

{
   "id":"urn:uuid:123e4567-e89b-12d3-a456-426655440000",
   "idShort":"Sensor_BNPL001000TS123_377-9efa-67gh023",
   "globalAssetId":"urn:uuid:123e4567-e89b-12d3-a456-426655440000",
   "displayName":[...],
   "description":[...],
   "assetKind":"Instance",
   "assetType":"urn:uuid:123e4567-e89b-12d3-a456-896655440001",
   "specificAssetIds":[
      {
         "name":"manufacturerId",
         "value":"123829238",
         "externalSubjectId":{
            "type":"ExternalReference",
            "keys":[
               {
                  "type":"GlobalReference",
                  "value":"BPN_COMPANY_002"
               }
            ]
         }
      },
      {
         "type":"GlobalReference",
         "name":"manufacturerPartId",
         "value":"231982",
         "externalSubjectId":{
            "type":"ExternalReference",
            "keys":[
               {
                  "type":"GlobalReference",
                  "value":"PUBLIC_READABLE"
               }
            ]
         }
      }
   ],
   "submodelDescriptors":[...],
   "groups":[...],
   "labels":[...]
}

Example G - Accessing the Asset Administration Shell Descriptor entity using public readable access

As shown below, the business partner 003 has access only to assets marked for public read access, and is not aware about the sharing details with other partners.

Also note that a user accessing a shell via public readable access has only access to the shell id, specificAssetIds and submodelDescriptors. Other fields are omitted.

{
   "id":"urn:uuid:123e4567-e89b-12d3-a456-426655440000",
   "specificAssetIds":[
      {
         "name":"manufacturerPartId",
         "value":"231982",
         "externalSubjectId":{
            "type":"ExternalReference",
            "keys":[
               {
                  "type":"GlobalReference",
                  "value":"PUBLIC_READABLE"
               }
            ]
         }
      }
   ],
   "submodelDescriptors":[...],
}

Grant read access to business partners

Closed by default and accessible only by the owner

Semantic meaning of the externalSubjectId attribute

Example A - Lock access to owner of the Asset Administration Shell

How read access is facilitated to data consumers

Enabling public readable access

Example B - Grant public readable access

Allow read access to particular BPNs

Example C - Grant access to specific BPN

Secure the list of BPNs having access

Combining the BPN-based and public readable read accesses and securing the read access list

Example D - Accessing the Asset Administration Shell Descriptor entity as owner

Example E - Accessing the Asset Administration Shell Descriptor entity as "BPN_COMPANY_001" BPN

Example F - Accessing the Asset Administration Shell Descriptor entity as "BPN_COMPANY_002" BPN

Example G - Accessing the Asset Administration Shell Descriptor entity using public readable access

Semantic meaning of the `externalSubjectId` attribute