-
Notifications
You must be signed in to change notification settings - Fork 2
/
change_pta.html
736 lines (577 loc) · 42.4 KB
/
change_pta.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Change PTA</title>
<link rel="stylesheet" href="./assets/w3.css" />
<link href="./assets/prism.css" rel="stylesheet" />
</head>
<body class="w3-container">
<h1>Access to data service</h1>
<p>In this section we describe the process of changing the PTA attribute of a packet delivery order via the packet delivery portal. The same process would be used when trying to change the PDA or delivery address.
</p>
<p>In the following the sequences are shown for the scenario of the Happy Pets customer changing the PTA of the delivery order. In the case of the No Cheaper customer, the sequences would be the same with the only difference being that the request for changing the PTA would be denied.
</p>
<h2>Sequence description (Happy Pets Customer)</h2>
<p>The following gives a detailed description of the process of changing the PTA attribute by the Happy Pets customer, when using Verifiable Credentials.
</p>
<p>In the interactions, Packet Delivery acts as a Relying Party (RP). The actual Trust Framework used in a real implementation will determine the DID associated to all the participants, but for this example we assume that the DID of Packet Delivery is <code>did:elsi:packetdelivery</code>. Additionally, Packet Delivery performs signatures using a private key associated to its DID and registered publicly in the Trust Framework (e.g., in the Trusted Participants List). The identification of the corresponding public key for signature verification in this example is <code>did:elsi:packetdelivery#key-verification</code>, where <code>key-verification</code> identifies the specific key used in a signature if the entity has several keys registered in the Trust Framework.
</p>
<p>The detailed sequence of interactions in this use case is the following:</p>
<ul>
<li>
<p><b>1.</b> Happy Pets customer directs her browser to access the Packet Delivery company portal.
</p>
</li>
<li>
<p><b>2.</b> The browser sends a request to the Packet Delivery portal server.
</p>
</li>
<li>
<p><b>3.</b> Happy Pets customer gets forwarded to a page for selecting the desired Identity Provider for login. One of the login options is “Login with Verifiable Credentials” or something similar.
</p>
</li>
<li>
<p><b>4.</b> Happy Pets customer selects the “Verifiable Credentials” login method, which causes the Packet delivery company portal to generate a QR containing inside the URL of the /authentication-requests endpoint of the RP (Relying Party) component of Packet Delivery. A QR code is used because a Self-Issued OP may be running locally as a native application or progressive web application (PWA), the RP may not have a network-addressable endpoint to communicate directly with the OP. We have to leverage the implicit flow of OpenID Connect to communicate with such locally-running Ops, as described in [<a href="#SIOPv2" class="xref">SIOPv2</a>].
</p>
<p>The QR code includes a nonce called <code>state</code> that will be used later by the portal to know when a specific login session has finished. In our use case, the URL inside the QR could look like this:</p>
<pre><code class="language-http">GET /authentication-requests?state=af0ifjsldkj HTTP/1.1
Host: rp.packetdelivery.com</code></pre>
</li>
<li>
<p><b>5.</b> The QR code is displayed in the customer browser with instructions to scan it and go to the URL inside it.
</p>
</li>
<li>
<p><b>6.</b> The customer scans the QR with her mobile and tells the mobile to go to the URL in the QR.
</p>
</li>
<li>
<p><b>7.</b> The mobile performs a GET request to the url inside the QR (e.g. https://www.packetdelivery.com/api/authentication-requests). This starts a standard SIOP (Self-Issued OpenID Provider) flow, where the Packet Delivery company plays the role of Relying Party (RP in Open ID Connect terminology) and the mobile device of the customer as a Self-Issued IDP (SIOP).
</p>
</li>
<li>
<p><b>8.</b> Packet Delivery company RP creates a SIOP Authentication Request. The parameters comprising a request for verifiable presentations are given in section 5 of [<a href="#OIDC4VP" class="xref">OIDC4VP</a>] and in section 10.1 of [<a href="#SIOPv2" class="xref">SIOPv2</a>] and are reproduced here with the particularities of this use case, in particular that this is a cross-device interaction:
</p>
<ul>
<li>
<p><b>response_type</b>: REQUIRED. Must be <b>"vp_token"</b>. This parameter is defined in [<a href="#RFC6749" class="xref">RFC6749</a>]. The possible values are determined by the response type registry established by [<a href="#RFC6749" class="xref">RFC6749</a>]. The [<a href="#OIDC4VP" class="xref">OIDC4VP</a>] specification introduces the response type <b>"vp_token"</b>. This response type asks the SIOP to return only a VP Token in the Authorization Response, which is what we want in our case.
</p>
</li>
<li>
<p><b>scope</b>: REQUIRED. This parameter is defined in [<a href="#RFC6749" class="xref">RFC6749</a>] which allows it to be used by verifiers to request presentation of credentials by utilizing a pre-defined scope value designating the type of credential. See section <a href="#request_scope" class="xref">Request Scope</a> for more details. We use in this instance the value <code>gaiax.credentials.presentation.CustomerCredential</code> which means that the RP (PacketDelivery) is asking the SIOP (customer wallet) to send a credential of type CustomerCredential issued by any participant in the ecosystem.
</p>
</li>
<li>
<p><b>response_mode</b>: REQUIRED. MUST be “post”. As this is a cross-device scenario, this response mode is used to request the Self-Issued OP to deliver the result of the authentication process to a certain endpoint using the HTTP POST method. This endpoint to which the SIOP shall deliver the authentication result is conveyed in the parameter <code>redirect_uri</code>.
</p>
</li>
<li>
<p><b>redirect_uri</b> (REQUIRED). MUST be a valid RP endpoint. The Authentication Response is sent to this endpoint using <code>POST</code> and encoding <code>application/json</code>)
</p>
</li>
<li>
<p><b>client_id</b>: REQUIRED. MUST be the DID of the RP (Packet Delivery in this case) so it can be resolved by the SIOP and checked against a Trusted List, or rejected if it does not pass validation. This provides a high level of assurance to the SIOP that the RP is really who it claims.
</p>
</li>
<li>
<p><b>nonce</b>: REQUIRED. This parameter follows the definition given in [<a href="#OpenID.Core" class="xref">OpenID.Core</a>]. It is used to securely bind the verifiable presentation(s) provided by the wallet (SIOP) to the particular transaction managed by the RP.
</p>
</li>
<li>
<p><b>state</b>: REQUIRED. Used by the portal component of Packet Delivery to associate the start of an authentication session with the end of that session when the RP component notifies to the portal.
</p>
</li>
<li>
<p><b>presentation_definition</b>: CONDITIONAL. A string containing a <code>presentation_definition</code> JSON object as defined in Section 4 of [<a href="#DIF.PresentationExchange" class="xref">DIF.PresentationExchange</a>]. We do not use this parameter because <code>scope</code> already specifies the credential type.
</p>
</li>
<li>
<p><b>presentation_definition_uri</b>: CONDITIONAL. A string containing a URL pointing to a resource where a <code>presentation_definition</code> JSON object as defined in Section 4 of [<a href="#DIF.PresentationExchange" class="xref">DIF.PresentationExchange</a>] can be retrieved. We do not use this parameter because <code>scope</code> already specifies the credential type.
</p>
</li>
</ul>
<p>Note: A request MUST contain either a <code>presentation_definition</code> or a <code>presentation_definition_uri</code> or a single <code>scope</code> value representing a presentation definition, those three ways to request credential presentation are mutually exclusive. We use here the <code>scope</code> mechanism.
</p>
<p>This is an example request (with newlines and leading spaces added for legibility):</p>
<div class="artwork art-text alignLeft">
<pre><code class="language-http">openid://?
<b>scope</b>=gaiax.credentials.presentation.CustomerCredential
&<b>response_type</b>=vp_token
&<b>response_mode</b>=post
&<b>client_id</b>=did:elsi:packetdelivery
&<b>redirect_uri</b>=https%3A%2F%2Fwww.packetdelivery.com%2Fapi%2Fsiop/authentication_response%2Fcb
&<b>state</b>=af0ifjsldkj
&<b>nonce</b>=n-0S6_WzA2Mj</code></pre>
</div>
</li>
<li>
<p><b>9.</b> The SIOP Authentication Request is returned to the mobile in the reply body of the GET request, as a JWT in JWS form ([<a href="#RFC7515" class="xref">RFC7515</a>]), signed with the public key associated with the DID in the client_id field of the Authorization Request. The JWT MUST be generated according to the best practices described in [<a href="#RFC8725" class="xref">RFC8725</a>]. This is an example of the unencoded contents of such JWT:
</p>
<pre><code class="language-json">--------------- Header ---------------
{
"alg": "ES256", // This should be one of the supported algorithms in the Data Space
"kid": did:elsi:packetdelivery#key-verification
"typ": "JWT"
}
--------------- Payload ---------------
{
"iss": did:elsi:packetdelivery, // Should correspond with the client_id in the AR
"iat": 1667194901,
"exp": 1667194961, // To avoid replays, here it expires in 60 secs
"auth_request": "openid://?scope=...&response_type=vp_token&...",
}
</code>
</pre>
<p>Where the claim <code>iss</code> MUST be the DID of the RP (in this case Packet Delivery) and correspond exactly with the <code>client_id</code> parameter in the Authentication Request. The claim <code>auth_request</code> contains the Authentication Request as a string. The expiration time in claim <code>exp</code> avoids replays and can be very short because it is used by the SIOP just on reception of the Authentication Request.
</p>
</li>
<li>
<p><b>10.</b> In this and steps 11 and 12 the customer SIOP verifies that the RP (in this case Packet Delivery) is a trusted entity belonging to the ecosystem, by resolving the DID of the RP received in the <code>client_id</code> parameter of the Authentication Request and verifying the signature of the JWT.
</p>
<p>Before starting DID resolution, we perform the standard verification of the JWT as described in [<a href="#RFC8725" class="xref">RFC8725</a>] and [<a href="#RFC7515" class="xref">RFC7515</a>], except for the signature. We also check for the existence of the claim <code>auth_request</code> in the JWT and that its contents are a well-formed Authentication Request.
</p>
<p>In addition, we get the DID of the RP from the <code>client_id</code> parameter of the Authentication Request received in the JWT, making sure that it corresponds exactly to the <code>iss</code> claim in the payload of the JWT.</p>
<p>We resolve that DID by sending a GET request to the <code>/api/did/v1/identifiers/{did}</code> endpoint of one of the Universal Resolvers in the ecosystem, where <code>{did}</code> should be the DID of the RP retrieved in the previous step (in our case the DID of Packet Delivery). The endpoint returns the DID Document corresponding to the DID of the RP.</p>
</li>
<li>
<p><b>11.</b> The DID Document (as per W3C) contains relevant information about the entity owning the DID, in particular:
</p>
<ul>
<li>The Public Key of the entity used to verify its digital signatures</li>
<li>Status of the entity in the Trusted Participant List</li>
</ul>
<p>The DID Document is extensible, and can contain any additional public information which may be relevant for the use case, like commercial name of the RP, website address, contact information, etc.
</p>
<p>An example DID Document (in this example stored in the Alastria RedT blockchain network) is:</p>
<pre><code class="language-json">
{
"payload": {
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/v1"
],
"id": "did:elsi:packetdelivery",
"verificationMethod": [
{
"id": "did:elsi:packetdelivery#key-verification",
"type": "JwsVerificationKey2020",
"controller": "did:elsi:packetdelivery",
"publicKeyJwk": {
"kid": "key-verification",
"kty": "EC",
"crv": "secp256k1",
"x": "V8XptJkb5wplYkExcTF4nkyYVp7t5H5d5C4UPqCCM9c",
"y": "kn3nSPxIIvd9iaG0N4v14ceuo8E4PcLXhhGeDzCE7VM"
}
}
],
"service": [
{
"id": "did:elsi:packetdelivery#info",
"type": "EntityCommercialInfo",
"serviceEndpoint": "https://www.packetdelivery.com/info",
"name": "Packet Delivery co."
},
{
"id": "did:elsi:packetdelivery#sms",
"type": "SecureMessagingService",
"serviceEndpoint": "https://www.packetdelivery.com/api/securemessage"
}
],
"anchors": [
{
"id": "redt.alastria",
"resolution": "UniversalResolver",
"domain": "packetdelivery.ala",
"ethereumAddress": "0xbcB9b29eeb28f36fd84f1CfF98C3F1887D831d78"
}
],
"created": "2021-11-14T13:02:37Z",
"updated": "2021-11-14T13:02:37Z"
}
}
</code></pre>
<p>The resolution process is implemented as follows:
<ol>
<li>Perform the standard verification of the JWT as described in [<a href="#RFC8725" class="xref">RFC8725</a>] and [<a href="#RFC7515" class="xref">RFC7515</a>], except for the signature.</li>
<li>Check for the existence of the claim <code>auth_request</code> in the JWT and that its contents are a well-formed Authentication Request.</li>
<li>Get the DID of the RP from the <code>client_id</code> parameter of the Authentication Request received in the JWT, making sure that it corresponds exactly to the <code>iss</code> claim in the payload of the JWT.</li>
<li>Send a GET request to the <code>/api/did/v1/identifiers/{did}</code> endpoint of one of the Universal Resolvers in the ecosystem, where <code>{did}</code> should be the DID of the RP retrieved in the previous step (in our case the DID of Packet Delivery). The endpoint returns the DID Document corresponding to the DID of the RP.</li>
<li>Perform the standard verifications on the DID Document as described in [<a href="#VC_DATA" class="xref">VC_DATA</a>]. In particular it is important to check that the DID inside the DID Document corresponds with the DID that was specified in the GET request.</li>
</ol>
</p>
<p>The Universal Resolver server used in this step has to be operated by an entity which is trusted by the customer. To minimize the required trust in the ecosystem there may be many Universal Resolver servers operated by different entities. At least one of those trusted entities has to be configured in the wallet of the user.
</p>
<p>The underlying Trusted Lists queried by the Universal Resolver can be implemented with any technology suitable for the ecosysmen. In this implementation FIWARE uses a Universal Resolver accessing a blockchain network with a Public-Permissioned model, where the Trusted Lists are managed</p>
</li>
<li>
<p><b>12.</b> After DID resolution, we need to check the signature of the JWT containing the Authorization Request.
</p>
<p>As mentioned above, the DID Document includes one or more public keys inside the <code>verificationMethod</code> array. The keys are identified by the <code>id</code> field in each element of the array. The customer wallet uses the <code>kid</code> field that was received in the Authentication Request (in the protected header of the JWT) to select the corresponding Public Key and verify the signature of the JWT. It also verifies that the top-level <code>id</code> field in the DID Document (<code>did:elsi:EU.EORI.NLPACKETDEL</code>) is equal to the <code>client_id</code> parameter of the Authentication Request.</p>
</li>
<li>
<p><b>13.</b> The customer wallet creates an Authentication Response to be posted in the <code>redirect_uri</code> specified by Packet Delivery company in step 8. The contents of the Authentication Response are described below.</p>
<p>The response is constructed as defined in section 6.1 of [<a href="#OIDC4VP" class="xref">OIDC4VP</a>]. In particular, because the Authorization Request included only <code>vp_token</code> as the <code>response_type</code>, the VP Token is provided directly in the Authorization Response and a separate <code>id_token</code> is not needed.</p>
<p>The contents of the Authentication Response in our specific use case are (shown here with the POST parameters needed to send it):</p>
<pre><code class="language-http">POST /api/siop/authentication_response/cb HTTP/1.1
Host: www.packetdelivery.com
Content-Type: application/x-www-form-urlencoded
presentation_submission=[see definition below]
&vp_token=[see definition below]
</code></pre>
<p>The content of the <code>presentation_submission</code> parameter in the above Authentication Request is:</p>
<pre><code class="language-json">{
"definition_id": "CustomerPresentationDefinition",
"id": "CustomerPresentationSubmission",
"descriptor_map": [
{
"id": "id_credential",
"path": "$",
"format": "ldp_vp",
"path_nested": {
"format": "ldp_vc",
"path": "$.verifiableCredential[0]"
}
}
]
}</code></pre>
<p>Which complies with [<a href="#DIF.PresentationExchange" class="xref">DIF.PresentationExchange</a>] and refers to the VP in the <code>vp_token</code> parameter provided in the same response, which looks as follows:</p>
<pre><code class="language-json">{
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"type": [
"VerifiablePresentation"
],
"verifiableCredential": [
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://happypets.fiware.io/2022/credentials/employee/v1"
],
"id": "https://happypets.fiware.io/credentials/25159389-8dd17b796ac0",
"type": [
"VerifiableCredential",
"CustomerCredential"
],
"issuer": {
"id": "did:elsi:happypets"
},
"issuanceDate": "2022-03-22T14:00:00Z",
"validFrom": "2022-03-22T14:00:00Z",
"expirationDate": "2023-03-22T14:00:00Z",
"credentialSubject": {
"id": "did:peer:99ab5bca41bb45b78d242a46f0157b7d",
"verificationMethod": [
{
"id": "did:peer:99ab5bca41bb45b78d242a46f0157b7d#key1",
"type": "JwsVerificationKey2020",
"controller": "did:peer:99ab5bca41bb45b78d242a46f0157b7d",
"publicKeyJwk": {
"kid": "key1",
"kty": "EC",
"crv": "P-256",
"x": "lJtvoA5_XptBvcfcrvtGCvXd9bLymmfBSSdNJf5mogo",
"y": "fSc4gZX2R3QKKfHvS3m2vGSVSN8Xc04qsquyfEM55Z0"
}
}
],
"roles": [
{
"target": "did:elsi:packetdelivery",
"names": [
"P.Info.gold"
]
}
],
"name": "Jane Doe",
"given_name": "Jane",
"family_name": "Doe",
"preferred_username": "j.doe",
"email": "janedoe@packetdelivery.com"
}
}
]
}</code></pre>
<p>The above Verifiable Presentation includes only one Verifiable Credential of type <code>CustomerCredential</code> that was issued by Happy Pets to a customer. The <code>credentialSubject</code> object in the credential has an <code>id</code> field with value <code>did:peer:99ab5bca41bb45b78d242a46f0157b7d</code> which is the DID of the user and that is not registered in any blockchain or centralized repository.</p>
</li>
<li>
<p><b>14.</b> The SIOP (customer wallet) sends the Authentication Response to the endpoint passed in the <code>redirect_uri</code> parameter of the Authentication Request, sending a HTTP POST request using <code>application/x-www-form-urlencoded</code> encoding.
</p>
</li>
<li>
<p><b>15 and 16.</b> The Packet Delivery RP component receives the Authorization Request and has to perform verifications, the standard ones being defined in [<a href="#DIF.PresentationExchange" class="xref">DIF.PresentationExchange</a>]. In order to verify that the Verifiable Credential has been issuer by a trusted participant in the ecosystem, Packet Delivery has to verify:</p>
<ol>
<li>That the DID of the entity which is the issuer of the VC is a trusted participant.</li>
<li>That the VC was digitally signed by that participant.</li>
</ol>
<p>Both verifications can be done by performing DID resolution, checking that the resulting DID Document contains the public key corresponding to the one specified in the Verifiable Credential, and by verifying the digital signature of the credential against that public key.</p>
<p>The process for DID resolution and getting the public key from the resulting DID Document is exactly the same as the one described in steps 10 and 11 before.
</p>
<p>Resolution is performed sending a GET request to a server implementing the Universal Resolver API with the DID of the issuer of the Verifiable Credential. In our case the DID is the value of the field <code>verifiableCredential[0].issuer.id</code> which is the DID of Happy Pets: <code>did:elsi:happypets</code>. Packet Delivery could use a Universal Resolver server operated by a different entity, but this would reduce the level of trust compared to using its own server, which is the recommended setup.
</p>
</li>
<li>
<p><b>17.</b> After verifying the credential, Packet Delivery can also verify that the Verifiable Presentation including the Verifiable Credential is sent by the customer and not by a malicious agent. To do so, it uses the Public Key of the customer in the <code>verificationMethod</code> of the <code>credentialSubject</code> structure. That public key is cryptographically bound to the customer DID during the onboarding process that Happy Pets performed with the customer.
</p>
</li>
<li>
<p><b>18.</b> The RP component of Packet Delivery sends a successful response to the POST request that the SIOP (customer wallet) used to send the Authorization Request to the RP. The wallet receives the response to the POST indicating the success or failure of the process. The RP component of Packet Delivery continues processing because the web portal of Packet Delivery has to be refreshed with the services that this specific customer can access, based on the information received in the Verifiable Credential and the access control policies implemented by Packet Delivery.
</p>
</li>
<li>
<p><b>19.</b> The RP component of Packet Delivery company creates an Access Token for the customer so she can use it to access services in Packet Delivery company in the future. The RP component generates an Access Token in JWT format signed by the RP component. The access token is intended for use as bearer token over HTTP/1.1 [RFC2616] using Transport Layer Security (TLS) [RFC5246] to access protected resources, and it should use the JWT Profile profile described in [<a href="#RFC9068" class="xref">RFC9068</a>].
</p>
<p>For our use case, the JWT access token looks like:</p>
<pre><code class="language-json">Header:
{"typ":"at+JWT","alg":"RS256","kid":"at-key"}
Claims:
{
"iss": "did:elsi:packetdelivery",
"sub": "did:peer:99ab5bca41bb45b78d242a46f0157b7d",
"aud": "https://contextbroker.packetdelivery.com/",
"exp": 1639528912,
"iat": 1618354090,
"jti" : "dbe39bf3a3ba4238a513f51d6e1691c4",
"client_id": "did:elsi:packetdelivery",
"scope": "vp_token",
"verifiableCredential": [the VC that was received inside the Verifiable Presentation]
}</code></pre>
<p>Where, according to [<a href="#RFC9068" class="xref">RFC9068</a>]:</p>
<ul>
<li><b>iss</b> and <b>client_id</b> have the same value because the access token has been generated by the RP component of Packet Delivery, not by an IdP as in the "classic" OIDC flows.</li>
<li><b>sub</b> identifies the customer using the DID inside the Verifiable Credential received</li>
<li><b>aud</b> identifies the RS (Resource Server) component in Packet Delivery. In this case we assume that it is internal and does not have a DID assigned, so we use the URI of the component.</li>
<li><b>kid</b> in the header identifies the key that is used to sign the JWT and which must be configured up-front and known by the RS (Resource Server.</li>
<li><b>scope</b> has the same value as the equivalent <b>scope</b> parameter in the initial Authorization Request.</li>
<li><b>verifiableCredential</b> contains the Verifiable Credential that was received, specifically the value of the first element of the field <code>verifiableCredential</code> of the Verifiable Presentation.</li>
</ul>
</li>
<li>
<p><b>20.</b> The RP component of Packet Delivery notifies the Portal to refresh the login page so it can present the services to the customer. The notification includes the following:</p>
<ol>
<li>The <code>state</code> nonce that was generated by the portal when it generated the QR code. The portal uses the <code>state</code> nonce to know what login session is notified.</li>
<li>The access token generated before.</li>
</ol>
<p>The notification is a simple POST request with both parameters in the body:</p>
<pre><code class="language-http">
POST /api/notify HTTP/1.1
Host: portal.packetdelivery.com
Content-Type: application/x-www-form-urlencoded
access_token=[the access token]
&state=af0ifjsldkj</code></pre>
<p>The portal component replies immediately and continues processing.</p>
</li>
<li>
<p><b>21.</b> The Packet Delivery portal refreshes the screen and displays the services available to customers, sending the Access Token to the browser of the customer.</p>
</li>
<li>
<p><b>22.</b> The customer selects the option "Change PTA on delivery order" and the browsers sends a GET request to the Packet Delivery portal, including the Access Token as a Bearer token in the Authorization header of the HTTP request. For example:</p>
<pre><code class="language-http">GET /resource HTTP/1.1
Host: contextbroker.example.com
Authorization: Bearer [the access token]</code></pre>
<p>The request is intercepted by the Policy Enforcement Point (PEP) component of Packet Delivery, an API gateway.</p>
</li>
<li>
<p><b>23.</b> The PEP checks that the request to the protected resource includes an Authorization header with a Bearer token, digitally signed by the RP component of Packet Delivery with one of the keys previously configured in the API gateway.</p>
</li>
<li>
<p><b>24.</b> The PEP asks the Policy Decision Point (PDP) to evaluate if the Access Token authorizes the caller to access the target service ("Change PTA on delivery order"). It forwards the original request including the Access Token to the PDP.</p>
</li>
<li>
<p><b>25 and 26.</b> The PDP uses information in the Access Token to retrieve from the Policy Retrieval Point (PRP)the relevant policy definitions required to evaluate authorization for the request. The PRP is where the access authorization policies are stored, typically a database or the filesystem.</p>
</li>
<li>
<p><b>27.</b> The PDP uses information in the Access Token and the policies retrieved from the PRP to evaluate policies associated to customer roles and any additional attributes in the token. One of the policies retrieved correwsponds to the purchasing status of the Happy Pets company with respect to the services provided by Packet Delivery.</p>
</li>
<li>
<p><b>28.</b> In our use case, the customer is of category Gold and Packet Delivery is currently paying for the Gold service so the evaluation of the policies grants access to the requested service ("Change PTA on delivery order").</p>
</li>
<li>
<p><b>29.</b> The PEP (API gateway) receives the successful reply and forwards the request, including the Access Token, to the RS (Resource Server). In this case to the Context Broker, not shown in the diagram.</p>
</li>
<li>
<p><b>30 and 31.</b> The request is executed and the reply is sent to the customer browser, where the customer can continue using the Packet Delivery portal for any other requests she may want to execute.</p>
</li>
</ul>
<section id="request_scope">
<h2 id="name-scope">
Request Scope
</h2>
<p>
According to section 5.3 of [<a href="#OIDC4VP" class="xref">OIDC4VP</a>], wallets MAY support requesting presentation of credentials using OAuth 2.0 scope values. Such a scope value MUST be an alias for a well-defined presentation definition as it will be refered to in the <code>presentation_submission</code> response parameter.
</p>
<p>
In this specification we define concrete scope values and the mapping between a certain scope value and the respective presentation definition, in particular the mapping between scope values and specific types of Verifiable Credentials used for access control in the use case described in this document. In a production implementation of a Data Space ecosystem, the Trust Framework has to define the mappings used in the ecosysyem and the mechanisms and governance models used to update those mappings.
</p>
<p>
The mappings that we will use in this use case are the following:
</p>
<p>
Scope <b>gaiax.credentials.presentation.EmployeeCredential</b> represents the following presentation definition:
</p>
<pre><code class="language-json">{
"id": "EmployeePresentationDefinition",
"input_descriptors": [
{
"id": "employee credential",
"format": {
"ldp_vc": {
"proof_type": [
"Ed25519Signature2018"
]
}
},
"constraints": {
"fields": [
{
"path": [
"$.type"
],
"filter": {
"type": "string",
"pattern": "EmployeeCredential"
}
}
]
}
}
]
}</code></pre>
<p>
Scope <b>gaiax.credentials.presentation.CustomerCredential</b>: represents the following presentation definition:
</p>
<pre><code class="language-json">{
"id": "CustomerPresentationDefinition",
"input_descriptors": [
{
"id": "customer credential",
"format": {
"ldp_vc": {
"proof_type": [
"Ed25519Signature2018"
]
}
},
"constraints": {
"fields": [
{
"path": [
"$.type"
],
"filter": {
"type": "string",
"pattern": "CustomerCredential"
}
}
]
}
}
]
}</code></pre>
</section>
<section id="section-11">
<h2 id="name-normative-references">
Normative References
</h2>
<dl class="references">
<dt id="VC_DATA">[VC_DATA]</dt>
<dd>
<span class="refAuthor">Sporny, M.</span><span class="refAuthor">, Noble, G.</span><span class="refAuthor">, Longley, D.</span><span class="refAuthor">, Burnett, D. C.</span><span class="refAuthor">, Zundel, B.</span><span class="refAuthor">, and D. Chadwick</span>, <span class="refTitle">"Verifiable Credentials Data Model 1.0"</span>, <time datetime="2019-11-19">19 November 2019</time>, <span><<a href="https://www.w3.org/TR/vc-data-model">https://www.w3.org/TR/vc-data-model</a>></span>.
</dd>
<dt id="RFC7515">[RFC7515]</dt>
<dd>
<span class="refAuthor">Jones, M.</span><span class="refAuthor">, Bradley, J.</span><span class="refAuthor">, and N. Sakimura</span>, <span class="refTitle">"JSON Web Signature (JWS)"</span>, <span class="seriesInfo">RFC 7515</span>, <span class="seriesInfo">DOI 10.17487/RFC7515</span>, <time datetime="2015-05">May 2015</time>, <span><<a href="https://www.rfc-editor.org/info/rfc7515">https://www.rfc-editor.org/info/rfc7515</a>></span>.
</dd>
<dt id="RFC8414">[RFC8414]</dt>
<dd>
<span class="refAuthor">Jones, M.</span><span class="refAuthor">, Sakimura, N.</span><span class="refAuthor">, and J. Bradley</span>, <span class="refTitle">"OAuth 2.0 Authorization Server Metadata"</span>, <span class="seriesInfo">RFC 8414</span>, <span class="seriesInfo">DOI 10.17487/RFC8414</span>, <time datetime="2018-06">June 2018</time>, <span><<a href="https://www.rfc-editor.org/info/rfc8414">https://www.rfc-editor.org/info/rfc8414</a>></span>.
</dd>
<dt id="RFC6749">[RFC6749]</dt>
<dd>
<span class="refAuthor">Hardt, D., Ed.</span>, <span class="refTitle">"The OAuth 2.0 Authorization Framework"</span>, <span class="seriesInfo">RFC 6749</span>, <span class="seriesInfo">DOI 10.17487/RFC6749</span>, <time datetime="2012-10">October 2012</time>, <span><<a href="https://www.rfc-editor.org/info/rfc6749">https://www.rfc-editor.org/info/rfc6749</a>></span>.
</dd>
<dt id="RFC8725">[RFC8725]</dt>
<dd>
<span class="refAuthor">Sheffer, Y.</span>, <span class="refAuthor">Hardt, D., Ed.</span>, <span class="refAuthor">and Jones, M.</span> <span class="refTitle">"JSON Web Token Best Current Practices"</span>, <span class="seriesInfo">RFC 8725</span>, <span class="seriesInfo">DOI 10.17487/RFC8725</span>, <time datetime="2020-02">February 2020</time>, <span><<a href="https://www.rfc-editor.org/info/rfc8725">https://www.rfc-editor.org/info/rfc8725</a>></span>.
</dd>
<dt id="RFC7515">[RFC7515]</dt>
<dd>
<span class="refAuthor">Jones, M.</span>, <span class="refAuthor">Bradley, J.</span>, <span class="refAuthor">and Sakimura, N.</span> <span class="refTitle">"JSON Web Signature (JWS)"</span>, <span class="seriesInfo">RFC 7515</span>, <span class="seriesInfo">DOI 10.17487/RFC7515</span>, <time datetime="2015-05">May 2015</time>, <span><<a href="https://www.rfc-editor.org/info/rfc7515">https://www.rfc-editor.org/info/rfc7515</a>></span>.
</dd>
<dt id="DIF.PresentationExchange">[DIF.PresentationExchange]</dt>
<dd>
<span class="refAuthor">Buchner, D.</span><span class="refAuthor">, Zundel, B.</span><span
class="refAuthor">, Riedel, M.</span><span class="refAuthor">, and K. H. Duffy</span>, <span
class="refTitle">"Presentation Exchange 2.0.0"</span>, <time></time>, <span><<a
href="https://identity.foundation/presentation-exchange">https://identity.foundation/presentation-exchange</a>></span>.
</dd>
<dt id="OpenID.Registration">[OpenID.Registration]</dt>
<dd>
<span class="refAuthor">Sakimura, N.</span><span class="refAuthor">, Bradley, J.</span><span
class="refAuthor">, and M. B. Jones</span>, <span class="refTitle">"OpenID Connect Dynamic Client
Registration 1.0 incorporating errata set 1"</span>, <time datetime="2014-11-08">8 November 2014</time>,
<span><<a
href="https://openid.net/specs/openid-connect-registration-1_0.html">https://openid.net/specs/openid-connect-registration-1_0.html</a>></span>.
</dd>
<dt id="DID-Core">[DID-Core]</dt>
<dd>
<span class="refAuthor">Sporny, M.</span><span class="refAuthor">, Guy, A.</span><span class="refAuthor">,
Sabadello, M.</span><span class="refAuthor">, and D. Reed</span>, <span class="refTitle">"Decentralized
Identifiers (DIDs) v1.0"</span>, <time datetime="2021-08-03">3 August 2021</time>, <span><<a
href="https://www.w3.org/TR/2021/PR-did-core-20210803/">https://www.w3.org/TR/2021/PR-did-core-20210803/</a>></span>.
</dd>
<dt id="RFC7591">[RFC7591]</dt>
<dd>
<span class="refAuthor">Richer, J., Ed.</span><span class="refAuthor">, Jones, M.</span><span class="refAuthor">, Bradley, J.</span><span class="refAuthor">, Machulak, M.</span><span class="refAuthor">, and P. Hunt</span>, <span class="refTitle">"OAuth 2.0 Dynamic Client Registration Protocol"</span>, <span class="seriesInfo">RFC 7591</span>, <span class="seriesInfo">DOI 10.17487/RFC7591</span>, <time datetime="2015-07">July 2015</time>, <span><<a href="https://www.rfc-editor.org/info/rfc7591">https://www.rfc-editor.org/info/rfc7591</a>></span>.
</dd>
<dt id="RFC9068">[RFC9068]</dt>
<dd>
<span class="refAuthor">Bertocci, V.</span>, <span class="refTitle">"JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens"</span>, <span class="seriesInfo">RFC 9068</span>, <span class="seriesInfo">DOI 10.17487/RFC9068</span>, <time datetime="2021-10">October 2021</time>, <span><<a href="https://www.rfc-editor.org/info/rfc9068">https://www.rfc-editor.org/info/rfc9068</a>></span>.
</dd>
<dt id="OpenID.Core">[OpenID.Core]</dt>
<dd>
<span class="refAuthor">Sakimura, N.</span><span class="refAuthor">, Bradley, J.</span><span class="refAuthor">, Jones, M.</span><span class="refAuthor">, de Medeiros, B.</span><span class="refAuthor">, and C. Mortimore</span>, <span class="refTitle">"OpenID Connect Core 1.0 incorporating errata set 1"</span>, <time datetime="2014-11-08">8 November 2014</time>, <span><<a href="http://openid.net/specs/openid-connect-core-1_0.html">http://openid.net/specs/openid-connect-core-1_0.html</a>></span>.
</dd>
<dt id="SIOPv2">[SIOPv2]</dt>
<dd>
<span class="refAuthor">Microsoft</span><span class="refAuthor">, Jones, M. B.</span><span class="refAuthor">, and T. Looker</span>, <span class="refTitle">"Self-Issued OpenID Provider V2"</span>, <time datetime="2021-07-20">20 July 2021</time>, <span><<a href="https://openid.bitbucket.io/connect/openid-connect-self-issued-v2-1_0.html">https://openid.bitbucket.io/connect/openid-connect-self-issued-v2-1_0.html</a>></span>.
</dd>
<dt id="OIDC4VP">[OIDC4VP]</dt>
<dd>
<span class="refAuthor">Terbu, O.</span><span class="refAuthor">, Lodderstedt, T.</span><span
class="refAuthor">, Yasuda, K.</span><span class="refAuthor">, Lemmon, A.</span><span
class="refAuthor">,
and T. Looker</span>, <span class="refTitle">"OpenID for Verifiable Presentations"</span>, <time
datetime="2021-05-20">20 May 2021</time>, <span><<a
href="https://openid.net/specs/openid-4-verifiable-presentations-1_0.html">https://openid.net/specs/openid-4-verifiable-presentations-1_0.html</a>></span>.
</dd>
<dt id="RFC4648">[RFC4648]</dt>
<dd>
<span class="refAuthor">Josefsson, S.</span>, <span class="refTitle">"The Base16, Base32, and Base64 Data
Encodings"</span>, <span class="seriesInfo">RFC 4648</span>, <span class="seriesInfo">DOI
10.17487/RFC4648</span>, <time datetime="2006-10">October 2006</time>, <span><<a
href="https://www.rfc-editor.org/info/rfc4648">https://www.rfc-editor.org/info/rfc4648</a>></span>.
</dd>
<dt id="OAuth.Responses">[OAuth.Responses]</dt>
<dd>
<span class="refAuthor">de Medeiros, B.</span><span class="refAuthor">, Scurtescu, M.</span><span
class="refAuthor">, Tarjan, P.</span><span class="refAuthor">, and M. Jones</span>, <span
class="refTitle">"OAuth 2.0 Multiple Response Type Encoding Practices"</span>, <time
datetime="2014-02-25">25 February 2014</time>, <span><<a
href="https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html">https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html</a>></span>.
</dd>
<dt id="OpenID.VCI">[OpenID.VCI]</dt>
<dd>
<span class="refAuthor">Lodderstedt, T.</span><span class="refAuthor">, Yasuda, K.</span><span
class="refAuthor">, and T. Looker</span>, <span class="refTitle">"OpenID for Verifiable Credential
Issuance"</span>, <time datetime="2022-06-20">20 June 2022</time>, <span><<a
href="https://openid.net/specs/openid-4-verifiable-credential-issuance.html">https://openid.net/specs/openid-4-verifiable-credential-issuance.html</a>></span>.
</dd>
</dl>
</section>
<script src="./assets/prism.js"></script>
</body>
</html>