From 1ff453f3c734ff08553a5a8d1df76c7c7ee7e460 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger Date: Wed, 3 Jul 2024 14:55:50 +0200 Subject: [PATCH 1/4] docs: add decision record about optional params in CatalogRequest --- .../README.md | 44 +++++++++++++++++++ docs/developer/decision-records/README.md | 1 + 2 files changed, 45 insertions(+) create mode 100644 docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md diff --git a/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md b/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md new file mode 100644 index 00000000000..612495549e3 --- /dev/null +++ b/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md @@ -0,0 +1,44 @@ +# Adding an additional parameter to the `CatalogRequest` (Management API) + +## Decision + +The `POST /catalog/request` endpoint to request a catalog will receive a new optional field in the request body with which the requesting participant (=consumer) can insert additional scopes into the DCP interaction. + +## Rationale + +In typical DCP interactions, the consumer derives the required scopes from the current request (e.g. policies, or existing agreements). This does not work for a Catalog request, because there is no request context. + +Further, in many dataspaces there are "default scopes", i.e. scopes that must be present on every DSP interaction, but these are static - they can't be changed at runtime. + +So if a provider offers assets, that are only available is a special (non-default) credential is presented, the consumer must be able to attach the respective scope strings to the access token. + +_NB: the information \_which_ scopes must be added, has to be conveyed out-of-band.\_ + +In other words, a consumer may know that a provider has certain assets available, but they have an access policy constraint on them, which makes them "invisible" unless a certain credential is presented. + +## Approach + +The `CatalogRequest` will receive a new field `parameters`, which is an extensible map. This map may contain an entry `additionalScopes` which is a list of scope strings (as per [DCP Specification, Section 3.1](https://github.com/eclipse-tractusx/identity-trust/blob/main/specifications/verifiable.presentation.protocol.md#31-access-scopes)): + +```json +{ + "@type": "CatalogRequest", + "counterPartyAddress": "http://provider-address.com", + "counterPartyId": "providerId", + "protocol": "dataspace-protocol-http", + "querySpec": { + //... + }, + "parameters": { + "additionalScopes": [ + "org.eclipse.edc.vc.type.AdditionalCredentialType1:read", + "org.eclipse.edc.vc.type.AdditionalCredentialType2:*", + ] + } +} +``` +Scope strings provided in that fashion will get added to the default scopes. + +NB: both the `parameters` map and the `additionalScopes` entry are _OPTIONAL_. + +This feature will be added in an Alpha version of the Management API first, specifically of `3.1.0-alpha`. The respective URL path will be `/v31alpha/api/management/catalog/request` as per our [deprecation policy](https://github.com/eclipse-edc/docs/tree/main/developer/decision-records/2024-05-27-maturity-levels-deprecation-policy). diff --git a/docs/developer/decision-records/README.md b/docs/developer/decision-records/README.md index 62f3fec6a5d..30b04ade5fb 100644 --- a/docs/developer/decision-records/README.md +++ b/docs/developer/decision-records/README.md @@ -57,3 +57,4 @@ - [2024-01-12 Dynamic Constraint Functions](./2024-01-12-dynamic-constraint-functions/) - [2024-05-24 Dataplane Selection Improvements](./2024-05-24-dataplane-selection-improvements/) - [2024-06-24 Api Authentication Configuration](./2024-06-24-api-authentication-configuration/) +- [2024-07-03 Additional CatalogRequest scope parameter](./2024-07-03-additional-catalogrequest-param/) From fce1f5aca8180804136ff5c41db1a980b36754d9 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger Date: Wed, 3 Jul 2024 15:03:57 +0200 Subject: [PATCH 2/4] DEPENDENCIES --- DEPENDENCIES | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/DEPENDENCIES b/DEPENDENCIES index 258425b3167..5175a5f8592 100644 --- a/DEPENDENCIES +++ b/DEPENDENCIES @@ -45,14 +45,14 @@ maven/mavencentral/com.github.cliftonlabs/json-simple/3.0.2, Apache-2.0, approve maven/mavencentral/com.github.docker-java/docker-java-api/3.3.6, Apache-2.0, approved, #10346 maven/mavencentral/com.github.docker-java/docker-java-transport-zerodep/3.3.6, Apache-2.0 AND (Apache-2.0 AND BSD-3-Clause), approved, #15251 maven/mavencentral/com.github.docker-java/docker-java-transport/3.3.6, Apache-2.0, approved, #7942 -maven/mavencentral/com.github.java-json-tools/btf/1.3, Apache-2.0 AND GPL-1.0-or-later AND LGPL-3.0-only AND Apache-2.0 AND LGPL-3.0-only, restricted, #15201 +maven/mavencentral/com.github.java-json-tools/btf/1.3, Apache-2.0 OR LGPL-3.0-only, approved, #15201 maven/mavencentral/com.github.java-json-tools/jackson-coreutils-equivalence/1.0, LGPL-3.0 OR Apache-2.0, approved, clearlydefined maven/mavencentral/com.github.java-json-tools/jackson-coreutils/2.0, Apache-2.0 OR LGPL-3.0-or-later, approved, #15186 maven/mavencentral/com.github.java-json-tools/json-patch/1.13, Apache-2.0 OR LGPL-3.0-or-later, approved, CQ23929 -maven/mavencentral/com.github.java-json-tools/json-schema-core/1.2.14, Apache-2.0 AND LGPL-2.1-or-later AND LGPL-3.0-only AND (Apache-2.0 AND GPL-1.0-or-later AND LGPL-3.0-only) AND Apache-2.0 AND LGPL-3.0-only, restricted, #15282 -maven/mavencentral/com.github.java-json-tools/json-schema-validator/2.2.14, Apache-2.0 OR LGPL-3.0-or-later, approved, CQ20779 -maven/mavencentral/com.github.java-json-tools/msg-simple/1.2, Apache-2.0 AND LGPL-2.1-or-later AND LGPL-3.0-only AND (Apache-2.0 AND GPL-1.0-or-later AND LGPL-3.0-only) AND Apache-2.0 AND LGPL-3.0-only, restricted, #15239 -maven/mavencentral/com.github.java-json-tools/uri-template/0.10, Apache-2.0 AND LGPL-3.0-only AND (Apache-2.0 AND GPL-1.0-or-later AND LGPL-3.0-only), restricted, #15288 +maven/mavencentral/com.github.java-json-tools/json-schema-core/1.2.14, Apache-2.0 OR LGPL-3.0-or-later, approved, #15282 +maven/mavencentral/com.github.java-json-tools/json-schema-validator/2.2.14, Apache-2.0 OR LGPL-3.0-or-later, approved, #15263 +maven/mavencentral/com.github.java-json-tools/msg-simple/1.2, Apache-2.0 OR LGPL-3.0-or-later, approved, #15239 +maven/mavencentral/com.github.java-json-tools/uri-template/0.10, , approved, #15288 maven/mavencentral/com.github.luben/zstd-jni/1.5.6-3, BSD-2-Clause, approved, clearlydefined maven/mavencentral/com.github.stephenc.jcip/jcip-annotations/1.0-1, Apache-2.0, approved, CQ21949 maven/mavencentral/com.google.code.findbugs/jsr305/2.0.1, BSD-3-Clause AND CC-BY-2.5 AND LGPL-2.1+, approved, CQ13390 @@ -356,7 +356,7 @@ maven/mavencentral/org.testcontainers/jdbc/1.19.8, Apache-2.0, approved, #10348 maven/mavencentral/org.testcontainers/junit-jupiter/1.19.8, MIT, approved, #10344 maven/mavencentral/org.testcontainers/kafka/1.19.8, MIT, approved, #14177 maven/mavencentral/org.testcontainers/postgresql/1.19.8, MIT, approved, #10350 -maven/mavencentral/org.testcontainers/testcontainers/1.19.8, Apache-2.0 AND MIT, approved, #10347 +maven/mavencentral/org.testcontainers/testcontainers/1.19.8, MIT, approved, #15203 maven/mavencentral/org.testcontainers/vault/1.19.8, MIT, approved, #10852 maven/mavencentral/org.xerial.snappy/snappy-java/1.1.10.5, Apache-2.0 AND (Apache-2.0 AND BSD-3-Clause), approved, #9098 maven/mavencentral/org.xmlresolver/xmlresolver/5.2.2, Apache-2.0, approved, clearlydefined From f961458d0d499c8e60b98dee03b39b538ba0b7dd Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger Date: Wed, 3 Jul 2024 16:54:28 +0200 Subject: [PATCH 3/4] pr remarks --- .../README.md | 28 +++++++++++++------ 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md b/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md index 612495549e3..16554598d3f 100644 --- a/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md +++ b/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md @@ -2,23 +2,30 @@ ## Decision -The `POST /catalog/request` endpoint to request a catalog will receive a new optional field in the request body with which the requesting participant (=consumer) can insert additional scopes into the DCP interaction. +The `POST /catalog/request` endpoint to request a catalog will receive a new optional field in the request body with +which the requesting participant (=consumer) can insert additional scopes into the DCP interaction. ## Rationale -In typical DCP interactions, the consumer derives the required scopes from the current request (e.g. policies, or existing agreements). This does not work for a Catalog request, because there is no request context. +In typical DCP interactions, the consumer derives the required scopes from the current request (e.g. policies, or +existing agreements). This does not work for a Catalog request, because there is no request context. -Further, in many dataspaces there are "default scopes", i.e. scopes that must be present on every DSP interaction, but these are static - they can't be changed at runtime. +Further, in many dataspaces there are "default scopes", i.e. scopes that must be present on every DSP interaction, but +these are static - they can't be changed at runtime. -So if a provider offers assets, that are only available is a special (non-default) credential is presented, the consumer must be able to attach the respective scope strings to the access token. +So if a provider offers assets, that are only available is a special (non-default) credential is presented, the consumer +must be able to attach the respective scope strings to the access token. _NB: the information \_which_ scopes must be added, has to be conveyed out-of-band.\_ -In other words, a consumer may know that a provider has certain assets available, but they have an access policy constraint on them, which makes them "invisible" unless a certain credential is presented. +In other words, a consumer may know that a provider has certain assets available, but they have an access policy +constraint on them, which makes them "invisible" unless a certain credential is presented. ## Approach -The `CatalogRequest` will receive a new field `parameters`, which is an extensible map. This map may contain an entry `additionalScopes` which is a list of scope strings (as per [DCP Specification, Section 3.1](https://github.com/eclipse-tractusx/identity-trust/blob/main/specifications/verifiable.presentation.protocol.md#31-access-scopes)): +The `CatalogRequest` will receive a new field `parameters`, which is an extensible map. This map may contain an +entry `additionalScopes` which is a list of scope strings (as +per [DCP Specification, Section 3.1](https://github.com/eclipse-tractusx/identity-trust/blob/main/specifications/verifiable.presentation.protocol.md#31-access-scopes)): ```json { @@ -31,14 +38,17 @@ The `CatalogRequest` will receive a new field `parameters`, which is an extensib }, "parameters": { "additionalScopes": [ - "org.eclipse.edc.vc.type.AdditionalCredentialType1:read", - "org.eclipse.edc.vc.type.AdditionalCredentialType2:*", + "org.eclipse.edc.vc.type.AdditionalCredentialType1:read", + "org.eclipse.edc.vc.type.AdditionalCredentialType2:*" ] } } ``` + Scope strings provided in that fashion will get added to the default scopes. NB: both the `parameters` map and the `additionalScopes` entry are _OPTIONAL_. -This feature will be added in an Alpha version of the Management API first, specifically of `3.1.0-alpha`. The respective URL path will be `/v31alpha/api/management/catalog/request` as per our [deprecation policy](https://github.com/eclipse-edc/docs/tree/main/developer/decision-records/2024-05-27-maturity-levels-deprecation-policy). +This feature will be added in an Alpha version of the Management API first, specifically of `3.1.0-alpha`. The +respective URL path will be `/v3.1alpha/api/management/catalog/request` as per +our [deprecation policy](https://github.com/eclipse-edc/docs/tree/main/developer/decision-records/2024-05-27-maturity-levels-deprecation-policy). From f49d066ac7cdc19d819575002c01b97963601fbd Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger Date: Fri, 5 Jul 2024 07:59:01 +0200 Subject: [PATCH 4/4] move scopes into root object --- .../README.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md b/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md index 16554598d3f..33e16f3ed09 100644 --- a/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md +++ b/docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md @@ -16,15 +16,14 @@ these are static - they can't be changed at runtime. So if a provider offers assets, that are only available is a special (non-default) credential is presented, the consumer must be able to attach the respective scope strings to the access token. -_NB: the information \_which_ scopes must be added, has to be conveyed out-of-band.\_ +_NB: the information which scopes must be added, has to be conveyed out-of-band._ In other words, a consumer may know that a provider has certain assets available, but they have an access policy constraint on them, which makes them "invisible" unless a certain credential is presented. ## Approach -The `CatalogRequest` will receive a new field `parameters`, which is an extensible map. This map may contain an -entry `additionalScopes` which is a list of scope strings (as +The `CatalogRequest` will receive a new nullable field `additionalScopes` which is a list of scope strings (as per [DCP Specification, Section 3.1](https://github.com/eclipse-tractusx/identity-trust/blob/main/specifications/verifiable.presentation.protocol.md#31-access-scopes)): ```json @@ -36,18 +35,16 @@ per [DCP Specification, Section 3.1](https://github.com/eclipse-tractusx/identit "querySpec": { //... }, - "parameters": { - "additionalScopes": [ - "org.eclipse.edc.vc.type.AdditionalCredentialType1:read", - "org.eclipse.edc.vc.type.AdditionalCredentialType2:*" - ] - } + "additionalScopes": [ + "org.eclipse.edc.vc.type.AdditionalCredentialType1:read", + "org.eclipse.edc.vc.type.AdditionalCredentialType2:*" + ] } ``` Scope strings provided in that fashion will get added to the default scopes. -NB: both the `parameters` map and the `additionalScopes` entry are _OPTIONAL_. +NB: the `additionalScopes` entry is _OPTIONAL_. This feature will be added in an Alpha version of the Management API first, specifically of `3.1.0-alpha`. The respective URL path will be `/v3.1alpha/api/management/catalog/request` as per