Aiming to assure data sovereignty and to protect companies from accepting contracts negotiations with policies which are not compliant to their company contract exchange guidelines, a solution for indicating which policies should be chosen from the contract catalog incoming from the EDC is provided.
When auto-negotiation is enabled for the assets or done for the digital twin registry assets, the policies must be specified.
| Asset | Auto-Negotiation | Manual Negotiation | Description |
|---|---|---|---|
| Digital Twin Registry | X | Just auto-negotiation is enabled, where the contract agreements get stored for optimizing the data retrieval process. The allowed policies can be configured in the helm chart value files. | |
| Aspect Model (Data Service) | X | X | Negotiation is always automatic, however the policies can be "manually selected" in the frontend if disabled. If no policy is send in the "agree" response the policy will be took from configuration. Just the policies provided in the configuration will be chosen, and will be allowed to negotiate. A filter from the catalog will be done for the contracts with valid policies. Allowing the user in the manual selection to chose the policy he wants. I case for the manual selection the user wants to be able to see all the policies the policyConfig.enabled from the passport configuration needs to be set to false. More information here |
Important
The Digital Product Passport application does not have any logic to check if the policy is valid in the network or if the partner retrieving information using SSI has the authorized policy permissions for accessing and using the asset. This logic is already covered by the Eclipse DataSpace Connector (EDC) which is consuming the information from the network in name of the digital product pass application.
In the helm charts configuration/charts/digital-product-pass/values.yaml two different policy configurations keys are in place:
| Key Path | Description |
|---|---|
backend.passport.policyCheck |
In this configuration the policies are going to be checked against the aspect models "assets" avaialable at the catalog. Its function is to act as a filter for the incoming policies. |
backend.digitalTwinRegistry.policyCheck |
In this configuration the policies configured are checked against the digital twin registry policies. It purpose is to select policies from the catalog in order to comply with the companies policy guidelines. |
In order to configure the policies and do the checks the configuration in both keys are identical:
| Key | Type | Description |
|---|---|---|
policyCheck.enabled |
Boolean | Indicates if the policy check is enabled or disabled. In case it is disabled the first policy available will chosen. |
policyCheck.strictMode |
Boolean | Defines if the policy check will be done strictly using hashes or by default comparing each the constraint against the configuration. More details in section "Vali |
policyCheck.policies |
Array of Policies | Contains the list of allowed policies to be chosen from the edc catalog. Its structure is approximated to the semantic of the policies. |
For each policy in policyCheck.policies a specific configuration needs to be specified:
| Key | Type | Description |
|---|---|---|
permission |
Array of Actions | Describes the permissions "constraints" and actions allowed at the incoming policies. Access and usage policies configuration. |
prohibition |
Array of Actions | Describes the prohibitions "constraints" and actions allowed at the incoming policies. |
obligation |
Array of Actions | Describes the obligations "constraints" and actions allowed at the incoming policies. |
Caution
Currently just the permission constraint is standardized in Catena-X. Check the following guide to learn and understand how the policies should be configured in Catena-X: catenax-eV/cx-odrl-profile
For each action in policies.permission or policies.prohibition or policies.obligation a specific configuration needs to be specified:
| Key | Type | Description | Optional |
|---|---|---|---|
action |
String | Specified the specific action identifier. Example: USE. |
|
logicalConstraint |
String | Specifies the logical constraint to be used in case more than one "constraint" is specified. | X |
constraints |
Array of Constraints | Specified the list of constraints allowed to be negotiated in the digital product pass applicaiton |
In the logicalConstraint at the moment three different keys are supported:
| Key | Number of Policies Allowed | Description |
|---|---|---|
odrl:and |
No Limit | If the policy incoming has a logical constraint from the AND logic door it will be checked against this property |
odrl:or |
No Limit | If the policy incoming has a logical constraint from the OR logic door it will be checked against this property |
null or key not specified |
1 | If the key is not specified or is null then just one constraint is allowed, if more constraints are mentioned just the first one will be selected |
Each and every individual constraint in constraints is configured in the following way
| Key | Type | Description |
|---|---|---|
leftOperand |
String | The left operand indicated which key is being specified for the right operand |
operator |
String | The operator stands in between the left and right operands, its the logic that specifies the constraints |
rightOperand |
String or Integer | The right operand indicates the value from the leftOperand key. |
Two available modes of comparison are available for the key strictMode.
| Key | strictMode value |
Description |
|---|---|---|
| Strict Mode | true |
Comparison using hashes. The two policies are parsed into the same "object" class in java so they adapt to the same structure, once it is done they will be hashed and compared. In this case the order from arrays of constraints and actions are relevand and it must be identical to the other policy. Because of the properties of hashes, since if one byte changes it would affect the result, creating a different hash. |
| Default Mode | false |
Comparison from each constraint and action against eachother. The two policies will be compared constraint by constraint using a permisive mode, where strings are compared ignoring if they are lowerCase or upperCase, and also the order from the constraints is not relevant. |
In the frontend the possibility to manually chose the policy is configured in this parameter frontend.negotiation.autoSign.
If the parameter is set to false the backend will automatically select the first valid policy available in the catalog and matching the policy configurations.
For viewing and understanding the latest information regarding the policy selection flow see th User Manual.
In this documentation some points and resources will be indicated:
If Auto sign setting is enabled, the first valid contract policy checked against the configuration is always chosen as shown in below screenshot. The passport is shown to the user as shown in a Passport Page.
This feature requires user action. If disabled, the contract policy must be choosen by the user from the popup menu during the loading process.
The sign feature basically signs the contract policy before the contract negotiation is done. The right contract policy must be selected by the user, otherwise the contract negotiation is aborted and user is returned back to the Main Menu.
In the Choose a policy dialog, there might be more than one policy listed. User needs to select the appropriate one and click on the Agree button.
The policy shown to the user, is written in Open Digital Rights Language (ODRL), which is translated into a more visual interpretation. For more information consult Policy Interpretation
This section defines how the policy can be interpreted to make it more understandable. The contract policy contains two different constraints separated by OR, AND or None logical constraints against the defined asset Id in a target:
Example of policy content: A user or company can have access to this policy either they have Membership equals to active or FrameworkAgreemen.sustainability equals to active.
In case the user want to see more details from the policy, it can be done by clicking in "More Details" which will display a JSON tree, with the complete policy and contract available for deep inspection.
NOTE: The contract policy is always checked against the defined asset Id in a target field
The user accepts the right contract policy, and click on the Agree button which resumes the remaining negotiation and data transfer steps. In the end, the passport data is retrieved and displays to the user Passport Page.
If a user is not permitted to accept a particular policy from his company, the contract policy can be declined in this case. The user will be redirected to the Main Menu.
In case the and operator is used here is the way how it would be configured. For this policy in JSON format:
{
"@context": {
"odrl": "http://www.w3.org/ns/odrl/2/",
"cx-policy": "https://w3id.org/catenax/policy/"
},
"@type": "PolicyDefinitionRequest",
"@id": "cx-policy",
"profile": "cx-policy:profile2405",
"policy": {
"@type": "Policy",
"odrl:permission": [
{
"odrl:action": "USE",
"odrl:constraint": {
"@type": "LogicalConstraint",
"odrl:and": [
{
"@type": "Constraint",
"odrl:leftOperand": {
"@id": "cx-policy:Membership"
},
"odrl:operator": {
"@id": "odrl:eq"
},
"odrl:rightOperand": "active"
},
{
"@type": "Constraint",
"odrl:leftOperand": {
"@id": "cx-policy:FrameworkAgreement"
},
"odrl:operator": {
"@id": "odrl:eq"
},
"odrl:rightOperand": "circulareconomy:1.0"
},
{
"@type": "Constraint",
"odrl:leftOperand": {
"@id": "cx-policy:UsagePurpose"
},
"odrl:operator": {
"@id": "odrl:eq"
},
"odrl:rightOperand": "cx.circular.dpp:1"
}
]
}
}
],
"odrl:obligation": [],
"odrl:prohibition": []
}
}The complete configuration in the passport section would be the following in YAML format with reduced complexity:
policyCheck:
enabled: true
strictMode: false # -- Can be enabled if order from constraints is important
policies:
- permission:
- action: "USE"
logicalConstraint: "odrl:and"
constraints:
- leftOperand: "cx-policy:Membership"
operator: "odrl:eq"
rightOperand: "active"
- leftOperand: "cx-policy:FrameworkAgreement"
operator: "odrl:eq"
rightOperand: "circulareconomy:1.0"
- leftOperand: "cx-policy:UsagePurpose"
operator: "odrl:eq"
rightOperand: "cx.circular.dpp:1"
prohibition: [ ]
obligation: [ ]In case of multiple allowed policies the configuration will look like this:
Tip
The prohibition and obligation constraints if empty can be omitted!
policyCheck:
enabled: true
strictMode: false # -- Can be enabled if order from constraints is important
policies:
# -- All three constraints must be there if the "odrl:and" constraint
- permission:
- action: "USE"
logicalConstraint: "odrl:and"
constraints:
- leftOperand: "cx-policy:Membership"
operator: "odrl:eq"
rightOperand: "active"
- leftOperand: "cx-policy:FrameworkAgreement"
operator: "odrl:eq"
rightOperand: "circulareconomy:1.0"
- leftOperand: "cx-policy:UsagePurpose"
operator: "odrl:eq"
rightOperand: "cx.circular.dpp:1"
prohibition: [ ]
obligation: [ ]
# -- Just one constraint is mentioned and without logical constraint
- permission:
- action: "USE"
constraints:
- leftOperand: "cx-policy:Membership"
operator: "odrl:eq"
rightOperand: "active"
prohibition: [ ]
obligation: [ ]
# -- Example with "odrl:or" logical constraint
- permission:
- action: "USE"
logicalConstraint: "odrl:or"
constraints:
- leftOperand: "cx-policy:FrameworkAgreement"
operator: "odrl:eq"
rightOperand: "circulareconomy:1.0"
- leftOperand: "cx-policy:FrameworkAgreement"
operator: "odrl:eq"
rightOperand: "pcf:1.0"
prohibition: [ ]
obligation: [ ]In case the policy is simple and has one constraint, no logicalConstraint shall be added.
policyCheck:
enabled: true
strictMode: false # -- Can be enabled if order from constraints is important
policies:
# -- Just one constraint is mentioned and without logical constraint
- permission:
- action: "USE"
constraints:
- leftOperand: "cx-policy:Membership"
operator: "odrl:eq"
rightOperand: "active"
prohibition: [ ]
obligation: [ ]In case another constraint is added just the first one will be considered:
policyCheck:
enabled: true
strictMode: false # -- Can be enabled if order from constraints is important
policies:
# -- Just one constraint is mentioned and without logical constraint
- permission:
- action: "USE"
# -- No logical constraint mentioned here
constraints:
# -- Just this constraint will be selected
- leftOperand: "cx-policy:Membership"
operator: "odrl:eq"
rightOperand: "active"
# -- This constraint will be ignored
- leftOperand: "cx-policy:UsagePurpose"
operator: "odrl:neq"
rightOperand: "cx.core.qualityNotifications:1"
prohibition: [ ]
obligation: [ ]
The reason behind this is that the policies without logical constraints look like this:
{
"@context": {
"odrl": "http://www.w3.org/ns/odrl/2/",
"cx-policy": "https://w3id.org/catenax/policy/"
},
"@type": "PolicyDefinitionRequest",
"@id": "cx-policy",
"profile": "cx-policy:profile2405",
"policy": {
"@type": "Policy",
"odrl:permission": [
{
"odrl:action": "USE",
"odrl:constraint": {
"odrl:leftOperand": {
"@id": "cx-poliy:Membership"
},
"odrl:operator": {
"@id": "odrl:eq"
},
"odrl:rightOperand": "active"
}
}
],
"odrl:obligation": [],
"odrl:prohibition": []
}
}If you want to have multiple single constraints do it like this:
policyCheck:
enabled: true
strictMode: false # -- Can be enabled if order from constraints is important
policies:
# -- Just one constraint is mentioned and without logical constraint
- permission:
- action: "USE"
# -- No logical constraint mentioned here
constraints:
# -- Just this constraint will be selected
- leftOperand: "cx-policy:Membership"
operator: "odrl:eq"
rightOperand: "active"
# -- Just one constraint is mentioned and without logical constraint
- permission:
- action: "USE"
# -- No logical constraint mentioned here
constraints:
# -- This constraint will be considered now
- leftOperand: "cx-policy:UsagePurpose"
operator: "odrl:neq"
rightOperand: "cx.core.qualityNotifications:1"
This work is licensed under the CC-BY-4.0.
- SPDX-License-Identifier: CC-BY-4.0
- SPDX-FileCopyrightText: 2022, 2024 BMW AG
- SPDX-FileCopyrightText: 2022, 2024 Henkel AG & Co. KGaA
- SPDX-FileCopyrightText: 2023, 2024 CGI Deutschland B.V. & Co. KG
- SPDX-FileCopyrightText: 2023, 2024 Contributors to the Eclipse Foundation
- Source URL: https://github.com/eclipse-tractusx/digital-product-pass