diff --git a/CHANGELOG.md b/CHANGELOG.md index cbdfeea9f7..3cfdebcc21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ### Added - Added tombstone icon to parts table and error description in parts detail view - Endpoint (assets/import/report/{importJobId}) for retrieving import report -- Added concept #436: intermediate status handling +- Added concept #568: Policy management +- Added concept #436: Intermediate status handling - Added add Parts view concept ### Changed diff --git a/docs/concept/#568-policy-management/#568-policy-management.md b/docs/concept/#568-policy-management/#568-policy-management.md new file mode 100644 index 0000000000..3151c0dc6d --- /dev/null +++ b/docs/concept/#568-policy-management/#568-policy-management.md @@ -0,0 +1,316 @@ +# #568 Policy management + +| Key | Value | +|---------------|--------------------------------------------------------------------------| +| Autor | @ds-crehm | +| Creation date | 08.02.2024 | +| Ticket Id | [#568](https://github.com/eclipse-tractusx/traceability-foss/issues/568) | +| State | WIP | + +# Table of Contents +1. [Overview](#overview) +2. [Summary](#summary) +3. [Requirements](#requirements) +4. [Out of scope](#out-of-scope) +5. [Concept](#concept) +6. [Glossary](#glossary) +7. [References](#references) +8. [Additional Details](#additional-details) + +# Overview +In the Catena-X ecosystem every partner can potentially communicate to every other connected partner. +To remain in control of their own data, each partner can use policies to place conditions on the access of their data. +In order to use these policies they must first be created and attached to the assets of a partner. + +# Summary +It must be possible for an Administrator of Trace-X to create, read, update and delete policies, which are then stored in the IRS policy store. + +# Requirements +- [ ] Frontend UI is implemented (see https://miro.com/app/board/uXjVO5JVoho=/?moveToWidget=3458764577267183586&cot=14) +- [ ] CRUD operations for policies are implemented +- [ ] Communication to IRS policy store is implemented +- [ ] Policies are used when sending notifications + +# Out of scope +- Policies used to define which assets to be consumed over the IRS -> IRS team + +# Concept + +## CREATE policies + +| | | +|-------------|---------------| +| HTTP method | POST | +| Endpoint | /api/policies | +| Parameters | - | + +### Request body +#### Example +```json +[ + { + "permissions": [ + { + "action": "USE", + "constraint": { + "and": [ + { + "leftOperand": "string", + "odrl:rightOperand": "string", + "operator": { + "@id": "odrl:eq" + } + } + ], + "or": [ + { + "leftOperand": "string", + "odrl:rightOperand": "string", + "operator": { + "@id": "odrl:eq" + } + } + ] + } + } + ], + "policyId": "f253718e-a270-4367-901b-9d50d9bd8462", + "validUntil": "2024-02-19T12:48:23.786Z" + } +] +``` + +### Responses + +| Code | Definition | +|------|-------------------------------------------| +| 201 | Policy created | +| 400 | Policy registration failed | +| 401 | No valid authentication credentials found | +| 403 | Authorization refused by server | +| 404 | Not found | + +___ +**Creation of policies:** +```mermaid +sequenceDiagram + participant FE + participant BE + participant IRSPolicyStore + participant DB + FE->>BE: POST /api/policies + activate BE + BE->>BE: Verify policy + alt Valid policy + BE->>IRSPolicyStore: POST /irs/policies + activate IRSPolicyStore + IRSPolicyStore->>DB: Save policy + IRSPolicyStore-->>BE: Success + deactivate IRSPolicyStore + BE-->>FE: 200 Success + else Invalid policy + BE-->>FE: 400 Bad request + deactivate BE + end +``` + +## GET policies + +| | | +|-------------|---------------| +| HTTP method | GET | +| Endpoint | /api/policies | +| Parameters | - | + +### Responses + +| Code | Definition | +|------|-------------------------------------------| +| 200 | Returns all policies | +| 401 | No valid authentication credentials found | +| 403 | Authorization refused by server | +| 404 | Not found | + +#### Examples +**200** +```json +[ + { + "permissions": [ + { + "action": "USE", + "constraint": { + "and": [ + { + "leftOperand": "string", + "odrl:rightOperand": "string", + "operator": { + "@id": "odrl:eq" + } + } + ], + "or": [ + { + "leftOperand": "string", + "odrl:rightOperand": "string", + "operator": { + "@id": "odrl:eq" + } + } + ] + } + } + ], + "policyId": "f253718e-a270-4367-901b-9d50d9bd8462", + "validUntil": "2024-02-19T12:48:23.786Z" + } +] +``` +___ +**Getting policies:** +```mermaid +sequenceDiagram + participant FE + participant BE + participant DB + FE->>BE: GET /api/policies + activate BE + BE->>DB: GET /api/policies + activate DB + DB-->>BE: Policies (JSON) + deactivate DB + BE-->>FE: Policies (JSON) + deactivate BE +``` + +## UPDATE policies + +| | | +|-------------|-----------------------------| +| HTTP method | PUT | +| Endpoint | /api/policies/{policy_id} | +| Parameters | policy_id (required string) | + +### Request body +#### Example +```json +[ + { + "permissions": [ + { + "action": "USE", + "constraint": { + "and": [ + { + "leftOperand": "string", + "odrl:rightOperand": "string", + "operator": { + "@id": "odrl:eq" + } + } + ], + "or": [ + { + "leftOperand": "string", + "odrl:rightOperand": "string", + "operator": { + "@id": "odrl:eq" + } + } + ] + } + } + ], + "policyId": "f253718e-a270-4367-901b-9d50d9bd8462", + "validUntil": "2024-02-19T12:48:23.786Z" + } +] +``` + +### Responses + +| Code | Definition | +|------|-------------------------------------------| +| 200 | Policy updated | +| 400 | Policy update failed | +| 401 | No valid authentication credentials found | +| 403 | Authorization refused by server | +| 404 | Not found | + +___ +**Updating policies:** +```mermaid +sequenceDiagram + participant FE + participant BE + participant IRSPolicyStore + participant DB + FE->>BE: PUT tracex/policy (&policy_id="ABC123") + BE->>BE: Verify policy + activate BE + alt Valid policy + BE->>IRSPolicyStore: PUT /irs/policy (&policy_id="ABC123") + activate IRSPolicyStore + IRSPolicyStore->>DB: Update policy + IRSPolicyStore-->>BE: Success + deactivate IRSPolicyStore + BE-->>FE: 200 Success + else Invalid policy + BE-->>FE: 400 Bad request + deactivate BE + end +``` + +## DELETE policies + +| | | +|-------------|-----------------------------| +| HTTP method | DELETE | +| Endpoint | /api/policies/{policy_id} | +| Parameters | policy_id (required string) | + +### Responses + +| Code | Definition | +|------|-------------------------------------------| +| 200 | Policy deleted | +| 400 | Policy deletion failed | +| 401 | No valid authentication credentials found | +| 403 | Authorization refused by server | +| 404 | Not found | + +___ +**Deleting policies:** +```mermaid +sequenceDiagram + participant FE + participant BE + participant IRSPolicyStore + participant DB + FE->>BE: DELETE /api/policy (&policy_id="ABC123") + activate BE + BE->>IRSPolicyStore: DELETE /irs/policy (&policy_id="ABC123") + activate IRSPolicyStore + IRSPolicyStore->>DB: Delete policy + IRSPolicyStore-->>BE: Success + deactivate IRSPolicyStore + BE-->>FE: 200 Success + deactivate BE +``` + +## Sending notifications + +![send-notification-policy-verification.png](send-notification-policy-verification.png) + +# Glossary + +| Abbreviation | Name | Description | +|--------------|------|---------------| +| | | | +| | | | + +# References +EDC policy definition: https://github.com/eclipse-tractusx/ssi-docu/blob/main/docs/architecture/cx-3-2/edc/policy.definitions.md + +# Additional Details +Given the dynamic nature of ongoing development, there might be variations between the conceptualization and the current implementation. For the latest status, refer to the documentation. diff --git a/docs/concept/#568-policy-management/send-notification-policy-verification.png b/docs/concept/#568-policy-management/send-notification-policy-verification.png new file mode 100644 index 0000000000..067819b319 Binary files /dev/null and b/docs/concept/#568-policy-management/send-notification-policy-verification.png differ diff --git a/docs/concept/#568-policy-management/send-notification-policy-verification.puml b/docs/concept/#568-policy-management/send-notification-policy-verification.puml new file mode 100644 index 0000000000..e5052ae015 --- /dev/null +++ b/docs/concept/#568-policy-management/send-notification-policy-verification.puml @@ -0,0 +1,106 @@ +@startuml + +title + ==Send Quality Investigation +end title + +autonumber "[00]" +autoactivate on + +box "Trace-X" +participant "Trace-X Frontend" as TraceX order 0 +participant "Trace-X Backend" as TraceXB order 1 +participant "Trace-X EDC Adapter" as NAdapter order 2 + +participant "EDC" as SEDC order 3 +end box +participant "IRS Policy Store" as PS order 4 +participant "Discovery Service" as DS order 5 +box "Receiver" +participant "EDC" as REDC order 6 +participant "Some (Traceability) App" as TraceApp2 order 7 +end box + +TraceApp2 -> REDC: Create EDC Asset for \n"Quality Investigation Receipt"\nwith ""DataAddress"" as ""HTTP POST"" endpoint +return OK +TraceApp2 -> REDC: Create Access Policy, Usage Policy, Contract Definition +return OK +TraceX -> TraceX: Select suspect child Part(s) / Batch(es) +deactivate TraceX +TraceX -> TraceXB: Create Quality Investigation +TraceXB -> TraceXB: Identify BPN for Suspect Part(s) / Batch(es) +deactivate TraceXB +TraceXB -> TraceXB: Create Notifications separated by BPN\nStatus := CREATED +deactivate TraceXB +TraceXB -> TraceX: Quality Investigation list +deactivate TraceXB +TraceX -> TraceXB: Release Notification(s) +deactivate TraceX +TraceXB -> DS: Resolve EDC Endpoint +rnote right TraceXB +BPN of Receiver +end note +return OK +TraceXB -> PS: Fetch policies for Receiver BPN +activate PS +PS --> TraceXB: Policies +TraceXB -> TraceXB: Verify if notification may be sent +rnote right TraceXB +Verification based on policy constraints +end note +deactivate TraceXB + +alt Notification may be sent +TraceXB -> TraceXB: Update Notification Status\nStatus := SENT +deactivate TraceXB +TraceXB -> NAdapter: Send Notification **Receipt** +rnote right TraceXB +Payload as described in the interface and API specification. +end rnote +NAdapter -> SEDC: Fetch Catalog +SEDC <--> REDC: Fetch Catalog +NAdapter -> NAdapter: Find and Select Contract +rnote right NAdapter +Find the correct contract offer with: + +"asset:prop:notificationtype": "qualityinvestigation", +"asset:prop:notificationmethod": "receive" +end rnote +deactivate NAdapter +NAdapter -> SEDC: Initiate Contract Negotiation +SEDC <--> REDC: Contract Negotiation +NAdapter -> SEDC: Initiate Data Transfer +SEDC <--> REDC: Establish Channel +NAdapter -> SEDC: POST /public/... +rnote right NAdapter +Payload as described in the interface and API specification. +end rnote +SEDC -> REDC: POST /public/... +rnote right SEDC +Payload as described in the interface and API specification. +end rnote +REDC -> TraceApp2: POST /notifications/qualityinvestigations/receive +rnote right REDC +Payload as described in the interface and API specification. +end rnote +rnote right REDC +The http path depends on the DataAddress +in the EDC Data Asset. Thus, it depends on the +(Trace) app. +end rnote +TraceApp2 -->REDC: ""201"" OK +REDC --> SEDC: ""201"" OK +SEDC --> NAdapter: ""201"" OK +NAdapter --> TraceXB: ""201"" OK +TraceXB -> TraceXB: Update Notification Status\nStatus := RECEIVED +deactivate TraceXB +TraceXB -> TraceX: Update Notification Status +deactivate TraceX +else Notification may not be sent +TraceXB -> TraceXB: Update Notification Status\nStatus := EXCEPTION +deactivate TraceXB +TraceXB -> TraceX: Update Notification Status +deactivate TraceXB +deactivate TraceX +end +@enduml