Grant read access with fine-grained access control policies
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 when using fine-grained access control.
| 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.
Granting access to Asset Administration Shell Descriptors
When using fine-grained access control policies, the Digital Twin Registry will find the policies which are relevant for the current request and enforce them to grant access to certain parts of the shells.
Starting with a clean slate
By default, shells are not accessible when the BPN does not belong to the owner. Sharing data must be a conscious decision, therefore the Digital Twin Registry requires access control policies to be created for the BPN.
Policies can only give more access
Each policy can only tell the Digital Twin Registry to show some part of the Asset Administration Shell Descriptor. As a result, having more policies can only grant broader access and never remove or hide details which were already made visible by other policies. Refer to the following diagram to see which parts can be controlled by fine-grained access control policies.
The visibility of the Asset Administration Shell Descriptor
For any Partner other than the owner, Asset Administration Shell Descriptor visibility depends on the existence of any matching policy. If there is a policy that matches the Asset Administration Shell Descriptor, then the Asset Administration Shell Descriptor will be visible, and the policy will be enforced to determine which parts of the Asset Administration Shell Descriptor should be returned to the Partner who originated the request.
A policy is matching if all rules are evaluated as true in the accessRules section of the policy. Currently, policy matching can be done using specificAssetId name and value pairs as seen in the example below.
In case of the example above, the policy matched, because the Asset Administration Shell Descriptor had a specificAssetId with the required manufacturerId and 000001000300 pair as defined in the policy snippet. As a result, this shell will be visible, and the applicable policies will be enforced.
Enforcing policies on visible Asset Administration Shell Descriptors
The visibility of the Asset Administration Shell Descriptor properties is controlled by rules from the objectModifications section of the access control policy. Refer to the subsections below to understand what the fine-grained access control policies can show or hide from a visible Asset Administration Shell Descriptor.
Shell details
Some properties of the Asset Administration Shell Descriptor can be hidden or displayed together using the shellDetails attribute in our policy. These properties are:
-
idShort
-
description
-
displayName
-
assetKind
-
assetType
-
groups
-
labels
When a matching policy grants access to the shellDetails, all these properties will be made visible, otherwise they will remain hidden.
| This object modification does not support any conditions at the moment, meaning that the shell details will be visible for each Asset Administration Shell Descriptor the policy matches without any additional conditions. |
Global Asset ID
Recognizing the unique importance of the globalAssetId of the Asset Administration Shell Descriptor, the Digital Twin Registry can show or hide the globalAssetId independent from the shellDetails using the globalAssetId attribute in the policy as seen below.
This object modification does not support any conditions at the moment, meaning that the globalAssetId will be visible for each Asset Administration Shell Descriptor the policy matches without any additional conditions.
|
Specifc Asset IDs
Access can be granted to the specificAssetIds based on:
-
their
name -
or their
nameandvalue
This means, that we can display specificAssetIds one by one if needed as seen on the picture below.
In the example above, only the highlighted customerPartId would have been displayed because the provided conditions did not match the other specificAssetIds from the policy snippet. If we wanted to show more specificAssetIds, we would need to use more rules in the objectModifications section of our policy to select each specificAssetId separately.
This object modification requires the use of conditions, the Digital Twin Registry does not allow granting access to "ALL" specificAssetId without restrictions.
|
Submodel Descriptors
Submodel Descriptors can be made visible based on their semanticId key values. If an applicable policy defines the same semanticId value as the one used in any of the semanticId.keys[*].value nodes, the Submodel Descriptor will be made visible as shown by the highlighted area in the image below.
This object modification requires the use of conditions, the Digital Twin Registry does not allow granting access to "ALL" submodelDescriptors without restrictions.
|
Assigning policies to BPNs
Each policy can be assigned to one or more BPN values to define which Partner the policy should apply to. This is also known as the scope of the policy.
Enabling public readable access
The fine-grained access control supports using public readable access (similar to the PUBLIC_READABLE case using the classic access control solution). In case of the fine-grained access control, we can define any policy and assign it to the PUBLIC_READABLE scope to make it applicable to any Partner with access to the Digital Twin Registry regardless of their BPN.