Cleanup EndpointProperty inconsistencies and specify authType (#218)

* Specify auth type property; clarify authorization property and make case consistent; remove incorrect bearer prefix; remove non-normative S3 reference * Add descriptions * Remove S3 reference * Remove S3 reference * Revert releases folder change
International-Data-Spaces-Association · Feb 15, 2024 · 123804a · 123804a
1 parent 19a7e8f
commit 123804a
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 13 deletions.
diff --git a/transfer/message/example/transfer-request-message.json b/transfer/message/example/transfer-request-message.json
@@ -3,16 +3,21 @@
   "@type": "dspace:TransferRequestMessage",
   "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
   "dspace:agreementId": "urn:uuid:e8dc8655-44c2-46ef-b701-4cffdc2faa44",
-  "dct:format": "dspace:S3_AWS_PUSH",
+  "dct:format": "example:HTTP_PUSH",
   "dspace:dataAddress": {
     "@type": "dspace:DataAddress",
     "dspace:endpointType": "https://w3id.org/idsa/v4.1/HTTP",
     "dspace:endpoint": "http://example.com",
     "dspace:endpointProperties": [
       {
         "@type": "dspace:EndpointProperty",
-        "dspace:name": "Authorization",
-        "dspace:value": "Bearer TOKEN-ABCDEFG"
+        "dspace:name": "authorization",
+        "dspace:value": "TOKEN-ABCDEFG"
+      },
+      {
+        "@type": "dspace:EndpointProperty",
+        "dspace:name": "authType",
+        "dspace:value": "bearer"
       }
     ]
   },

diff --git a/transfer/message/example/transfer-start-message.json b/transfer/message/example/transfer-start-message.json
@@ -10,8 +10,13 @@
     "dspace:endpointProperties": [
       {
         "@type": "dspace:EndpointProperty",
-        "dspace:name": "Authorization",
-        "dspace:value": "Bearer TOKEN-ABCDEFG"
+        "dspace:name": "authorization",
+        "dspace:value": "TOKEN-ABCDEFG"
+      },
+      {
+        "@type": "dspace:EndpointProperty",
+        "dspace:name": "authType",
+        "dspace:value": "bearer"
       }
     ]
   }

diff --git a/transfer/transfer.process.binding.https.md b/transfer/transfer.process.binding.https.md
@@ -105,16 +105,21 @@ Authorization: ...
   "@type": "dspace:TransferRequestMessage",
   "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
   "dspace:agreementId": "urn:uuid:e8dc8655-44c2-46ef-b701-4cffdc2faa44",
-  "dct:format": "dspace:S3_AWS_PUSH",
+  "dct:format": "example:HTTP_PUSH",
   "dspace:dataAddress": {
     "@type": "dspace:DataAddress",
     "dspace:endpointType": "https://w3id.org/idsa/v4.1/HTTP",
     "dspace:endpoint": "http://example.com",
     "dspace:endpointProperties": [
       {
         "@type": "dspace:EndpointProperty",
-        "dspace:name": "Authorization",
-        "dspace:value": "Bearer TOKEN-ABCDEFG"
+        "dspace:name": "authorization",
+        "dspace:value": "TOKEN-ABCDEFG"
+      },
+      {
+        "@type": "dspace:EndpointProperty",
+        "dspace:name": "authType",
+        "dspace:value": "bearer"
       }
     ]
   },
@@ -165,8 +170,13 @@ Authorization: ...
     "dspace:endpointProperties": [
       {
         "@type": "dspace:EndpointProperty",
-        "dspace:name": "Authorization",
-        "dspace:value": "Bearer TOKEN-ABCDEFG"
+        "dspace:name": "authorization",
+        "dspace:value": "TOKEN-ABCDEFG"
+      },
+      {
+        "@type": "dspace:EndpointProperty",
+        "dspace:name": "authType",
+        "dspace:value": "bearer"
       }
     ]
   }
@@ -298,8 +308,13 @@ Authorization: ...
     "dspace:endpointProperties": [
       {
         "@type": "dspace:EndpointProperty",
-        "dspace:name": "Authorization",
-        "dspace:value": "Bearer TOKEN-ABCDEFG"
+        "dspace:name": "authorization",
+        "dspace:value": "TOKEN-ABCDEFG"
+      },
+      {
+        "@type": "dspace:EndpointProperty",
+        "dspace:name": "authType",
+        "dspace:value": "bearer"
       }
     ]
   }

diff --git a/transfer/transfer.process.protocol.md b/transfer/transfer.process.protocol.md
@@ -93,6 +93,10 @@ The Transfer Request Message is sent by a [Consumer](../model/terminology.md#con
 - The `dataAddress` contains a transport-specific endpoint address for pushing the data. It may include a temporary authorization via the `endpointProperties` property.
 - `callbackAddress` is a URI indicating where messages to the [Consumer](../model/terminology.md#consumer) should be sent. If the address is not understood, the [Provider](../model/terminology.md#provider) MUST return an UNRECOVERABLE error.
 
+- The `endpointProperties` may contain the following optional values:
+  - `authorization` - An opaque authorization token that clients must present when accessing the transport-specific endpoint address. 
+  - `authType` - The auth token type. For example, the value may be `bearer`. If present, this value may be used in conjunction with transport rules to define how the client must present an authorization token.   
+
 Note that [Providers](../model/terminology.md#provider) should implement idempotent behavior for [Transfer Request Messages](#21-transfer-request-message) based on the value of `consumerPid`. [Providers](../model/terminology.md#provider) may choose to implement idempotent behavior for a certain period of time. For example, until a TP has completed and been archived after an implementation-specific expiration period, repeated sending of [Transfer Request Messages](#21-transfer-request-message) does not change the state of the TP. If a request for the given `consumerPid` has already been received *and* the same [Consumer](../model/terminology.md#consumer) sent the original message again, the [Provider](../model/terminology.md#provider) should respond with an appropriate [Transfer Start Message](#22-transfer-start-message).
 
 - Once a TP has been created, all associated callback messages must include a `consumerPid` and `providerPid`.
@@ -114,6 +118,9 @@ Note that [Providers](../model/terminology.md#provider) should implement idempot
 The Transfer Start Message is sent by the [Provider](../model/terminology.md#provider) to indicate the data transfer has been initiated.
 
 - The `dataAddress` is only provided if the current transfer is a pull transfer and contains a transport-specific endpoint address for obtaining the data. It may include a temporary authorization via the `endpointProperties` property.
+- The `endpointProperties` may contain the following optional values:
+  - `authorization` - An opaque authorization token that clients must present when accessing the transport-specific endpoint address. 
+  - `authType` - The auth token type. For example, the value may be `bearer`. If present, this value may be used in conjunction with transport rules to define how the client must present an authorization token.   
 
 ### 2.3 Transfer Suspension Message
 
@@ -185,4 +192,4 @@ The Transfer Error is an object returned by a [Consumer](../model/terminology.md
 | `consumerPid` | UUID          | The TF unique id on [Consumer](../model/terminology.md#consumer) side. |
 | `providerPid` | UUID          | The TF unique id on [Provider](../model/terminology.md#provider) side. |
 | `code`        | string        | An optional implementation-specific error code.                        |
-| `reasons`     | Array[object] | An optional array of implementation-specific error objects.            |
+| `reasons`     | Array[object] | An optional array of implementation-specific error objects.            |