forked from hesusruiz/did-method-elsi
-
Notifications
You must be signed in to change notification settings - Fork 2
/
onboarding.rite
1607 lines (1096 loc) · 102 KB
/
onboarding.rite
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
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: Onboarding example with LEARCredential using did:elsi
editors:
- name: "Jesus Ruiz"
email: "hesusruiz@gmail.com"
company: "JesusRuiz"
companyURL: "https://hesusruiz.github.io/hesusruiz"
authors:
- name: "Jesus Ruiz"
email: "hesusruiz@gmail.com"
company: "JesusRuiz"
companyURL: "https://hesusruiz.github.io/hesusruiz"
- name: "Jörg Langkau "
email: "jlangkau@nicos-ag.com"
company: "nicos AG"
companyURL: "https://www.nicos-ag.com/"
copyright: >
Copyright © 2023 the document editors/authors. Text is available under the
<a rel="license" href="https://creativecommons.org/licenses/by/4.0/legalcode">
Creative Commons Attribution 4.0 International Public License</a>
latestVersion: "https://alastria.github.io/did-method-elsi/onboarding.html"
edDraftURI: "https://alastria.github.io/did-method-elsi/onboarding.html"
github: "https://github.com/alastria/did-method-elsi/blob/main/onboarding.rite"
og_description: >
Onboarding example with LEARCredential using did:elsi
og_site_name: LEARCredential and DID:ELSI Method
rite:
codeStyle: dracula
localBiblio:
"ETSI-CERTOVERVIEW":
title: "ETSI EN 319 412-1 V1.4.2 (2020-07) - Electronic Signatures and Infrastructures (ESI); Certificate Profiles; Part 1: Overview and common data structures"
href: "https://www.etsi.org/deliver/etsi_en/319400_319499/31941201/01.04.02_20/en_31941201v010402a.pdf"
date: "2020-07"
publisher: "ETSI"
"ETSI-LEGALPERSON":
title: "ETSI EN 319 412-3 V1.2.1 (2020-07) - Electronic Signatures and Infrastructures (ESI); Certificate Profiles; Part 3: Certificate profile for certificates issued to legal persons"
href: "https://www.etsi.org/deliver/etsi_en/319400_319499/31941203/01.02.01_60/en_31941203v010201p.pdf"
date: "2020-07"
publisher: "ETSI"
"ETSI-JADES":
title: "ETSI TS 119 182-1 V1.1.1 (2021-03) - Electronic Signatures and Infrastructures (ESI); JAdES digital signatures; Part 1: Building blocks and JAdES baseline signatures"
href: "https://www.etsi.org/deliver/etsi_ts/119100_119199/11918201/01.01.01_60/ts_11918201v010101p.pdf"
date: "2021-03"
publisher: "ETSI"
"DEP-DSS":
title: "Algorithm for Validation of qualified and advanced signatures and seals"
href: "https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Qualified+electronic+signature+-+QES+validation+algorithm"
date: "2019-10"
publisher: "European Commission"
"DID-Core":
title: "Decentralized Identifiers (DIDs) v1.0"
date: "19 July 2022"
href: "https://www.w3.org/TR/did-core/"
"DID-PRIMER":
title: "DID Primer"
href: "https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-fall2017/blob/master/topics-and-advance-readings/did-primer.md"
publisher: "Rebooting the Web of Trust 2017"
"DID-ELSI":
title: "DID ETSI Legal person Semantic Identifier Method Specification (did:elsi)"
href: "https://alastria.github.io/did-method-elsi/"
date: "04 June 2023"
"DID-DNS":
title: "The Decentralized Identifier (DID) in the DNS"
href: "https://tools.ietf.org/html/draft-mayrhofer-did-dns-01"
status: "Internet Draft"
publisher: "IETF"
"DIF.PresentationExchange":
title: "Presentation Exchange 2.0.0"
href: "https://identity.foundation/presentation-exchange/spec/v2.0.0/"
"OWASP-TRANSPORT":
title: "Transport Layer Protection Cheatsheet"
href: "https://www.owasp.org/index.php/Transport_Layer_Protection_Cheat_Sheet"
"OpenID.Core":
title: "OpenID Connect Core 1.0 incorporating errata set 1"
href: "http://openid.net/specs/openid-connect-core-1_0.html"
date: "8 November 2014"
"OpenID.VCI":
title: "OpenID for Verifiable Credential Issuance"
date: "3 February 2023"
href: "https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html"
"OpenID.SIOP2":
title: "Self-Issued OpenID Provider v2"
date: "28 January 2022"
href: "https://openid.bitbucket.io/connect/openid-connect-self-issued-v2-1_0.html"
"OpenID.VP":
title: "OpenID for Verifiable Presentations"
date: "21 April 2023"
href: "https://openid.net/specs/openid-4-verifiable-presentations-1_0.html"
"RFC6749":
title: "The OAuth 2.0 Authorization Framework"
href: "https://www.rfc-editor.org/rfc/rfc6749.html"
"RFC8414":
title: "OAuth 2.0 Authorization Server Metadata"
href: "https://www.rfc-editor.org/rfc/rfc8414"
"RFC7515":
title: "JSON Web Signature (JWS)"
href: "https://www.rfc-editor.org/rfc/rfc7515"
"RFC8725":
title: "JSON Web Token Best Current Practices"
href: "https://www.rfc-editor.org/rfc/rfc8725"
"RFC7519":
title: "JSON Web Token (JWT)"
href: "https://www.rfc-editor.org/rfc/rfc7519"
---
<section #abstract>
A common problem in ecosystems like Data Spaces is how organisations can onboard the ecosystem in a trusted and automated way, avoiding manual paperwork.
This document describes how the process of onboarding can be performed by an employee of an organisation, who has been appointed to do so by a legal representative of the organisation using eIDAS certificates and Verifiable Credentials.
The appointed employee will perform the process by using a special type of Verifiable Credential called `LEARCredential` (from <b>L</b>egal <b>E</b>ntity <b>A</b>ppointed <b>R</b>epresentative).
Any Verifier that trusts the eIDAS Trust Framework will be able to verify that:
<ul>
- <b>The person presenting the LEARCredential is the same as the one identified in the credential</b>
- <b>A legal representative of the organisation has attested that the person has the powers described in the credential</b>
This enables the person presenting the LEARCredential to start the onboarding process and also to provide any additional required documentation, preferably as additional Verifiable Credentials to enable automatic verification of compliance with the onboarding requirements (including Gaia-X credentials issued by the Compliance Service of Gaia-X).
The concept of LEARCredential is not limited to onboarding, even though in this document we focus on that specific use case. But LEARCredentials of different types can be used for delegating some limited powers to employees for other use cases.
<section id="conformance">
<section>Introduction
A common problem in ecosystems like Data Spaces is how organisations can onboard the ecosystem in a trusted and automated way, avoiding manual paperwork.
This document describes how the process of onboarding can be performed by an employee of an organisation, who has been appointed to do so by a legal representative of the organisation using eIDAS certificates and Verifiable Credentials.
The appointed employee will perform the process by using a special type of Verifiable Credential called `LEARCredential` (from <b>L</b>egal <b>E</b>ntity <b>A</b>ppointed <b>R</b>epresentative).
To achieve a high level of legal certainty under eIDAS, the LEARCredential is:
<ul>
- signed or sealed with an eIDAS certificate which is either:
<ul>
- a <b>certificate for electronic seals</b> issued to a legal person by a Qualified Trust Service Provider, or
- a <b>certificate for electronic signatures</b>, issued to a <b>legal representative of the legal person</b> by a Qualified Trust Service Provider.
- signed using the <b>JSON Advanced Electronic Signature</b> format described in [[[ETSI-JADES]]]
The LEARCredential includes claims identifying the employee and a description of the concrete powers that have been delegated by the legal representative of the organisation.
By signing/sealing the credential with an eIDAS certificate, the legal representative attests that the powers described in the credential have been delegated to the employee (maybe under some conditions, also described in the credential).
In this way, the LEARCredential has the same legal status as any other document in other formats (e.g., PDF) signed in an eIDAS-compliant way, but with all the advantages provided by the Verifiable Credential format.
In addition, the LEARCredential includes cryptographic material that allows the appointed employee to <b>use the credential as an online authentication mechanism</b> in an onboarding portal, by proving that the holder of the credential is the same person identified in the credential.
Any Verifier that trusts the eIDAS Trust Framework will be able to verify that:
<ul>
- <b>The person presenting the LEARCredential is the same as the one identified in the credential</b>
- <b>A legal representative of the organisation has attested that the person has the powers described in the credential</b>
This enables the person presenting the LEARCredential to start the onboarding process and also to provide any additional required documentation, preferably as additional Verifiable Credentials to enable automatic verification of compliance with the onboarding requirements (including Gaia-X credentials issued by the Compliance Service of Gaia-X).
Both types of eIDAS certificates mentioned above are an electronic attestation <b>that links electronic seal/signature validation data to a legal person and confirms the name of that person</b>. This way, the certificate, usually linked to the sealed/signed document, can be used to verify the identity of the creator of the seal/signature and whether the document has been sealed/signed using the corresponding private key.
Before issuing a certificate like the above, the Qualified Trust Service Provider (QTSP) performs validations against `Authentic Sources` to authenticate the identity of the organisation:
<ul>
- The data concerning the business name or corporate name of the organisation.
- The data relating to the constitution and legal status of the subscriber.
- The data concerning the extent and validity of the powers of representation of the applicant.
- The data concerning the tax identification code of the organisation or equivalent code used in the country to whose legislation the subscriber is subject.
The person controlling the above certificates will appoint a legal entity representative (LEAR) by generating and signing a Verifiable Credential which:
<ul>
- Includes identification data of an employee of the organisation
- Includes claims stating the delegation of specific powers to perform onboarding on behalf of the organisation
- Includes a public key where the corresponding private key is controlled by the employee, enabling him to prove that he is the holder of the credential when it is being used in an authentication process like the onboarding process described in this document.
The LEARCredential uses the `did:elsi` method for the identifiers of legal persons involved in the process, to facilitate the DID resolution and linkage with the eIDAS certificates. The `did:elsi` method is specified in [[[DID-ELSI]]].
The high-level view of the process is described in the following diagram, when a COO (Chief Operating Officer) appoints an employee to perform the onboarding process:
<x-diagram .plantuml>High level view of issuance of LEARCredential
box "Company" #WhiteSmoke
actor "Employee of company" as employee
participant "COO of company" as COO
end box
control "Trust Service Provider" as TSP
database "Authentic Sources" as registry
COO -> TSP ++: Request a\ncertificate for signatures
TSP <-> registry: Verify trusted data
TSP -> COO --: Provide certificate for signature
COO -> employee: Issue LEARCredential
<section>Participants
Here we introduce the actors of the reference use case we are going to have. The main actors are marked in yellow in the following diagram.
RealTruth is a Trust Service Provider operating under the eIDAS Trust Framework, which issues a certificate for seals to the company GoodAir. GoodAir is a business that provides some services using an Air Quality application operated by GoodAir.
RealTruth also provides a certificate for signatures to the COO of the GoodAir company, so the COO can use the certificate to sign documents on behalf of GoodAir (like contracts, invoices, financial reports, ...) in a way that is compliant with eIDAS.
The COO of GoodAir will issue a verifiable credential of type LEARCredential to an employee of GoodAir, signing the credential with his certificate for signatures.
<x-diagram .d2>
classes: {
participant: {
style: {
fill: "aqua"
}
}
multiple: {
style: {
multiple: true
}
}
}
eIDAS: eIDAS Trust Framework {
icon: images/eu_trust_mark.jpg
}
eIDAS.style.fill: transparent
DE_TL: Germany Trusted List
RealTruth: RealTruth TSP {
Seal: Certificate\nfor seal
Seal.shape: oval
Sign: Certificate\nfor signature
Sign.shape: oval
}
RealTruth.class: participant
OtherG: Other TSPs {
S3.shape: circle
S3: Cert\nfor Sign
S4.shape: circle
S4: Cert\nfor Seal
}
OtherG.class: multiple
DE_TL -> RealTruth
DE_TL -> OtherG
Other_Countries: Other Trusted Lists
Other_Countries.style.fill: transparent
Other_Countries.class: multiple
TSP1 {
S1.shape: circle
S1: Cert\nfor Sign
S2.shape: circle
S2: Cert\nfor Seal
}
TSPn {
S3.shape: circle
S3: Cert\nfor Sign
S4.shape: circle
S4: Cert\nfor Seal
}
GoodAir {
COO
Employee
}
GoodAir.class: participant
eIDAS -> DE_TL
eIDAS -> Other_Countries
RealTruth.Seal -> GoodAir: Issue Cert for Seals {
style: {
font-size: 30
}
}
RealTruth.Sign -> GoodAir.COO: Issue Cert for Signatures {
style: {
font-size: 30 }
}
Other_Countries -> TSP1
Other_Countries -> TSPn
GoodAir.COO -> GoodAir.Employee: LEARCredential {
style: {
font-size: 30
}
}
<section #participant>GoodAir: the company that wants to perform the onboarding process
The new participant is a business providing an Air Quality Monitoring application as a service. The business is called GoodAir and it operates the application, which receives data from a set of sensors that may or may not be the property of GoodAir. The sensors must have received a certification to be able to operate and send data to the GoodAir application.
The company is registered in the tax agency and business registry of Spain with VAT number <b>VATES-12345678</b>.
<section>COO (Chief Operating Officer) of GoodAir
The GoodAir company is small and the only person that can sign contracts on behalf of the company is the COO (Chief Operating Officer). The COO is a legal representative of the company and she is registered as so in the business registry of Spain.
The COO has a certificate for electronic signatures issued by one of the TSPs in Spain enabling the COO to perform electronic qualified signatures as legal representative of GoodAir, instead of doing them manually.
The X.509 certificate of the COO has the following contents in the `Subject` field (the example below is derived from a real certificate but with the identifiers modified to be an example):
<x-code .ini>
cn = 56565656V Jesus Ruiz
serialNumber = 56565656V
givenName = Jesus
sn = Ruiz
2.5.4.97 = VATES-12345678
o = GoodAir
c = ES
2.5.4.13 = Notary:Juan Lopez/Protocol Num:7172/Date:07-06-2021
The above set of fields bind the legal identity of the COO with the identity of the business:
<ul>
- `serialNumber` is the unique number recognized by the Spanish Government for spanish citizens (called NIF).
- `2.5.4.97` is the <a href="https://oidref.com/2.5.4.97">official OID for `organizationIdentifier`</a>. The contents of this field in the example certificate is the unique identifier for the legal person GoodAir.
Before issuing a certificate like the above, the TSP has to perform some validations to ensure that in the official source of truth (the business registry of Spain in this case) there is already registered information that states that the COO has indeed powers to act on behalf of GoodAir as a legal representative.
<section>RealTruth: a Trust Service Provider
RealTruth is an EU TSP, which appears in the TL (Trusted List) maintained by the <a href="https://tl.bundesnetzagentur.de/TL-DE.XML">German Government</a>.
RealTruth is a TSP based in Germany but operates in most of the countries of the EU and so being able to provide Trust Services across many countries, including Spain.
As all TSPs in the TLs of the Member States, its entry in the TL includes one or more "Services" entries which describe the Trust Services provided by the TSP.
A TSP can have one Service issuing certificates for signatures, another service issuing certificates for seals, another service for timestamping, etc.
The regulator approves or suspends each service from a TSP individually, and the services are the root anchor for a given trust environment.
In our case, the entry for RealTruth in the TL includes a `\<TSPService\>` entry, and inside it the `\<ServiceDigitalIdentity\>` entry includes a DER-encoded certificate specifying the digital identity of the root anchor for that trust domain. The certificate for the Service has in the Subject field:
<x-code .INI>
2.5.4.97 = VATDE-170173453
CN = DRV QC 11 MA CA 2017ca
OU = QC 11 Mitarbeiter CA
O = Deutsche Rentenversicherung Westfalen
C = DE
Which in the `organizationIdentifier` field (OID 2.5.4.97) specifies the unique organisation identifier assigned by the German regulatory authority to the TSP: VATDE-170173453.
RealTruth provides `Legal Person Representative Certificates` which are qualified in accordance with Regulation (EU) No. 910/2014 of the European Parliament and of the Council of 23 July 2014 on electronic identification and trust services for electronic transactions in the internal market.
The certification policies of RealTruth includes the following sentences:
<blockquote>
The Registration Authority must verify the following information in order to authenticate the identity of the organisation:
<ul>
- The data concerning the business name or corporate name of the organisation.
- The data relating to the constitution and legal status of the subscriber.
- <b>The data concerning the extent and validity of the powers of representation of the applicant.</b>
- The data concerning the tax identification code of the organisation or equivalent code used in the country to whose legislation the subscriber is subject.
The TSP (RealTruth in this case) performs the verifications against `Authentic Sources`.
<blockquote>
Authentic Sources are the public or private repositories or systems recognised or required by law containing attributes about a natural or legal persons.
The Authentic Sources in scope of Annex VI of the [eIDAS2] legislative proposal are sources for attributes on address, age, gender, civil status, family composition, nationality, education and training qualifications titles and licences, professional qualifications titles and licences, public permits and licences, financial and company data.
Authentic Sources in scope of Annex VI are required to provide interfaces to Qualified Electronic Attestation of Attributes (QEAA) Providers to verify the authenticity of the above attributes, either directly or via designated intermediaries recognised at national level.
Authentic Sources may also issue (Q)EAA-s themselves if they meet the requirements of the eIDAS Regulation. It is up to the Member States to define terms and conditions for the provisioning of these services, but according to the minimum technical specifications, standards, and procedures applicable to the verification procedures for qualified electronic attestations of attributes.
In accordance to the policies, RealTruth made those validations when issuing the certificate to the COO, in such a way that the Relying Parties verifying the certificate can have a high level of trust in the assertion that the natural person identified in the certificate (with Spanish ID of 56565656V) is a legal representative of he GoodAir company (organizationIdentifier VATES-12345678).
<section>John Doe: an administrative employee of GoodAir
This is an employee of the central administration department of GoodAir, who is going to be formally nominated to manage the onboarding process of GoodAir in the Data Space and some other operations in the Data Space once GoodAir is onboarded.. In particular, this employee is going to be nominated as a LEAR (Legal Entity Appointed Representative).
As its name implies, the LEAR has to be nominated by a <b>legal representative</b> of the GoodAir organisation with the necessary legal authority to commit the organisation for this type of decision. In our case, the COO of GoodAir will nominate John Doe as the LEAR of GoodAir, delegating to him the capabilities to perform onboarding in the DOME and some other associated tasks. That means that John Doe will not be empowered to perform other actions like onboarding on other Data Spaces or signing contracts or invoices on behalf of GoodAir.
To perform the nomination, the COO of GoodAir (a legal representative of GoodAir) will issue a special credential to John Doe and will sign the credential with his certificate for signatures as legal representative of GoodAir. The details are described later in this document.
<section>DOME: an instance of a Data Space for Smart Cities
DOME is a Data Space where local governments can procure data and services from other entities that act as service providers. At the same time, the local governments can also act as data and service providers for other entities in the Data Space.
The DOME Data Space has an onboarding service that allows external entities to perform onboarding in an automated fashion by using Verifiable Credentials that have been issued by trusted entities. The complete Trust Framework used by DOME is composed from a series of Trust Frameworks, some managed internally using a governance model of DOME and some others managed externally but by trusted entities. At the root of the Trust Framework of DOME is the eIDAS Trust Framework and the pan-european recognized list of Trust Service Providers issuing the eIDAS compliant digital identities, in the form of certificates for signatures/seals.
In order to participate in DOME, every legal person requires a certificate for seals or that one of its legal representatives has a certificate for signatures (or both). The DOME entity is registered in France with VAT number <b>VATFR-99999999</b>.
<section>The LEARCredential
In this example the LEARCredential will be generated using the certificate of the COO.
The credential will be generated with an application that the COO will use as VC Issuer and that allows the employee to receive the credential using his credential wallet, using [[OpenID.VCI]] to achieve compliance with the EUDI Wallet ARF.
The application enables the COO to specify the information required to create the LEARCredential, specifying the employee information and the specific type of LEARCredential. In general, there may be different instances of LEARCredentials for different purposes. One employee can have more than one LEARCredential, each having a different delegation of powers for different environments.
<section>Claims identifying the employee
These are claims identifying the subject of the credential, the person who will act as LEAR. Each Data Space can define their own depending on their specific requirements. For our example, we use the same that are used for accessing the EC portal. The claims in the credential are the digital equivalent of their analog counterparts, displayed here for illustration.
<figure #lear-appointment-letter-1>
<img src="images/lear-appointment-letter-1.png" alt="" />
<figcaption>LEAR subject identification data.
From the above form we can derive the following claims:
<x-code .json>
{
"title": "Mr.",
"first_name": "John",
"last_name": "Doe",
"gender": "M",
"postal_address": "",
"email": "johndoe@goodair.com",
"telephone": "",
"fax": "",
"mobile_phone": "+34787426623"
}
<section>DID of the employee
In this example we use the `did:key` method for the DID of the employee, which provides a very high level of privacy and given the way the LEARCredential is generated it supports the verification of the chain of responsibility with a proper level of guarantee.
If the highest levels of assurance and legal compliance is desired and the employee has an eIDAS certificate for signatures (in this case a personal one, not one like the COO), we could use the `elsi:did` for identification of the employee. However, the company (GoodAir) should make sure that the employee is aware of and agree to the possible privacy implications of doing so, given the personal details leaked from the eIDAS certificate.
Those "exposed" personal details are exactly the same as if the employee signs any "normal" document with a digital certificate, but care should be taken by GoodAir because in this case the signature would be done "on behalf of" his employer and not as an individual personal action.
Even though this is not unique to the `did:elsi` method, this also implies that the onboarding service has to handle those personal details in the same way as if it would be accepting any other document signed with a certificate for signatures, and ensure compliance with GDPR.
In this example we assume the usage of the `did:key` method for the employee to protect his privacy as much as possible.
This DID for the employee is an additional claim to the ones presented above, using the `id` field in the `credentialSubject` object. The DID corresponds to a keypair that was generated during the LEARCredential issuance process, where the private key was generated by the wallet of the employee and it was always under his control.
This private key controlled by the employee can be used to sign challenges from Relying Parties that receive the credential to prove that the person sending the credential is the same person that is identified in the `credentialSubject` object of the LEARCredential.
An example could be:
<x-code .json>
{
"id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
}
In this example, the signatures performed with the private key can not be JAdES-compliant ([[ETSI-JADES]]), but if the LEARCredential is attached to any other credential that is signed with this private key, then they can be traced up to the eIDAS certificate of the COO and so the chain of responsibility can be determined..
With the DID for the employee, the set of claims identifying him would be then:
<x-code .json>
{
"id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
"title": "Mr.",
"first_name": "John",
"last_name": "Doe",
"gender": "M",
"postal_address": "",
"email": "johndoe@goodair.com",
"telephone": "",
"fax": "",
"mobile_phone": "+34787426623"
}
<section>`legalRepresentative`
This section identifies the natural person (the COO) who is a legal representative of the legal person (GoodAir) and that is nominating the employee identified in the credential.
<x-code .json>
"legalRepresentative": {
"cn": "56565656V Jesus Ruiz",
"serialNumber": "56565656V",
"organizationIdentifier": "VATES-12345678",
"o": "GoodAir",
"c": "ES"
}
<x-note>Attributes for natural and legal persons
The attributes for natural persons and legal persons are derived from the <a href="https://ec.europa.eu/digital-building-blocks/wikis/download/attachments/467109280/eidas_saml_attribute_profile_v1.0_2.pdf?version=1&modificationDate=1639417533738&api=v2">eIDAS SAML Attribute Profile (eIDAS Technical Sub-group, 22 June 2015)</a>.
All attributes for the eIDAS minimum data sets can be derived from the <a href="https://ec.europa.eu/isa2/solutions/core-vocabularies_en/">ISA Core Vocabulary</a> and <a href="https://joinup.ec.europa.eu/collection/semic-support-centre/specifications">https://joinup.ec.europa.eu/collection/semic-support-centre/specifications</a>.
In the case of natural persons refer to the <a href="https://joinup.ec.europa.eu/asset/core_person/asset_release/core-person-vocabulary">Core Person Vocabulary</a> and in the case of legal persons refer to definitions for <a href="https://joinup.ec.europa.eu/asset/core_business/asset_release/core-business-vocabulary">Core Business Vocabulary</a>.
<section>`rolesAndDuties` of the LEAR
The `rolesAndDuties` object points to an externally hosted object with the roles and duties of the LEAR. This external object can be either a machine-interpretable definition of the roles and duties in the credential, or just an external definition of the roles and duties in natural language. The ideal approach is the first option, expressing the semantics with a proper machine-readable language, because this will allow automatic access control at the granularity of the individual sentences of that expression language. The `rolesAndDuties` object can also have the definition embedded into it, instead of having a pointer to an external object.
For illustration, the following figure shows an external object with some of the roles and duties in our LEAR example, in natural language.
<figure #lear-appointment-letter-2>
<img src="images/lear-appointment-letter-2.png" alt="" />
<figcaption>LEAR roles and duties.
A simplistic implementation of the object inside the credential could be:
<x-code .json>
"rolesAndDuties": [
{
"type": "LEARCredential",
"id": "https://dome-marketplace.eu//lear/v1/6484994n4r9e990494"
}
]
Where the last part of the url can correspond to the hash of the external linked document to ensure that any modification or tampering can be detected.
<section>Assembling the pieces together
With the above values for the example, the complete LEARCredential would become something like this:
<x-code .json>
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://dome-marketplace.eu//2022/credentials/learcredential/v1"
],
"id": "urn:did:elsi:25159389-8dd17b796ac0",
"type": ["VerifiableCredential", "LEARCredential"],
"issuer": {
"id": "did:elsi:VATES-12345678"
},
"issuanceDate": "2022-03-22T14:00:00Z",
"validFrom": "2022-03-22T14:00:00Z",
"expirationDate": "2023-03-22T14:00:00Z",
"credentialSubject": {
"id": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
"title": "Mr.",
"first_name": "John",
"last_name": "Doe",
"gender": "M",
"postal_address": "",
"email": "johndoe@goodair.com",
"telephone": "",
"fax": "",
"mobile_phone": "+34787426623",
"legalRepresentative": {
"cn": "56565656V Jesus Ruiz",
"serialNumber": "56565656V",
"organizationIdentifier": "VATES-12345678",
"o": "GoodAir",
"c": "ES"
},
"rolesAndDuties": [
{
"type": "LEARCredential",
"id": "https://dome-marketplace.eu//lear/v1/6484994n4r9e990494"
}
]
}
}
<section>The LEARCredential as a VerifiableID
DOME has an onboarding service that enables automatic self-onboarding of legal entities. In DOME when an entity (a
legal person or a natural person acting on behalf of a legal person) wants to perform an action on a protected
resource, we use Verifiable Credentials to perform authentication of the entity and then access control based on the
content of the Verifiable Credential(s) presented by that entity, and possibly additional authorisation information
that the Relying Party considers relevant for controlling access to the protected resource (for example, the
contractual status of the resource, time of the day or other context information).
<section>The VerifiableID as a type of Verifiable Credential
Not all types of Verifiable Credentials can be used for authentication, so for the purpose of this discussion we use the
same taxonomy as <a href="https://ec.europa.eu/digital-building-blocks/wikis/display/EBSIDOC/Data+Models+and+Schemas">defined in EBSI</a>:
<x-diagram .ditaa>The LEARCredential is a Verifiable Authorisation and a VerifiableID
+-----------------+
| |
| W3C Verifiable |
| Credential |
| |
+-----------------+
^
|
extends
|
+--------+--------+
| |
| Verifiable |
| Attestation |
| |
+-----------------+
^
|
extends
|
/--------------------+-------------------\
| | |
+------+--------+ +------+-------+ +------+--------+
| | | | | Other |
| Verifiable | | Verifiable | | Verifiable |
| Authorisation | | ID | | Attestations |
| | | | | |
+---------------+ +--------------+ +---------------+
^ ^
| extends |
\---------+----------/
|
+--------+---------+
| |
| |
| LEARCredential |
| |
|cGRE |
+------------------+
The full explanation is in the EBSI site, but for our purposes an example is enough.
In the case of a Diploma as a Verifiable Credential (a Verifiable Diploma), it is a Verifiable Attestation which indicates that the subject has certain skills or has achieved certain learning outcomes through formal or non-formal learning context. However, as in the case with normal Diplomas in paper of PDF format, this credential can be presented by anyone that holds the credential. In other words, the credential binds the identity of the subject with the claims inside the credential, but does not bind the identity of the holder of the credential with the identity of the subject of the credential, which requires a special mechanism in the issuance process.
Instead, <b>a `VerifiableID` is a special form of a Verifiable Credential that a natural or legal person can use in an electronic identification process as evidence of whom he/she/it is</b> (comparable with a passport, physical IDcard, driving licence, social security card, member-card…).
In general, in an authentication and access control process, the entity willing to perform an action has to present (in a Verifiable Presentation) a VerifiableID and possibly one or more additional Verifiable Attestations. Of course, if the VerifiableID already contains all the information required by the Relying Party, then only one credential is required in the process.
Most Verifiable Credentials will be issued as Verifiable Attestations, acting as efficient machine-processable and verifiable equivalent to their analog counterparts. Their purpose is to attest some attributes about the subject of the credential and not act as a mechanism for online authentication.
VerifiableIDs can be of different types and be issued by different entities with different levels of assurance (in eIDAS terminology). They are issued with the purpose of serving as authentication mechanisms in online processes. In the near future, VerifiableIDs of the highest level of assurance (LoA High) will be issued to citizens and businesses by their governments under eIDAS2.
<section>The LEARCredential for some identification processes
But <b>any entity can issue VerifiableIDs</b>, though the acceptance by Relying Parties can not be ensured because it is the Relying Party the only one deciding if it trusts on the issuer and its process for generating the VerifiableID.
DOME will make use of the future eIDAS2 VerifiableIDs when they are available and when they make sense in the context of DOME. But DOME defines some specific types of VerifiableIDs that are derived from eIDAS certificates for signatures/seals using the regulated standards for signatures, achieving a level of assurance that provides an acceptable level of legal certainty and reduced risk of repudiation.
An example is the LEARCredential described in a section above, which has the same level of legal certainty as any document signed with the same certificates (like a contract or an invoice).
Similarly, a Product provider (like GoodAir) who decides to use the DOME Trust and IAM framework or a compatible one for managing access to associated services by customers of their products will typically define specific types of VerifiableIDs if the standard ones in DOME or the existing and widely accepted ones are not suitable for the provider. In general, if a provider can use an existing and already used VerifiableID then it will facilitate potential customers access to its product because issuers of the VerifiableID do not have to modify or adapt their existing issuing processes.
<section>Issuing the LEARCredential
<section>Overview
In this example we use what we call a <i>profile</i> of the [[OpenID.VCI]] protocol. The standard is very flexible, and we restrict the different options available in the standard and implement a set of the options with given values that are adequate for our use case, without impacting flexibility in practice.
The following figure describes the main components that interact in the issuance of a credential in this profile.
The description of the issuance process is general enough to be used for many types of credentials, but the text includes notes describing the concrete application of the process to the case of the LEARCredential.
<figure #iss-overview>
<img src="images/issuance/issuance_background.svg" alt="" />
<figcaption>Overview of participants.
<b>End user</b>
This profile is valid for both natural and juridical persons, but because we are focusing on the issuance of the LEARCredential, in the detailed examples below we assume a natural person as the user.
<b>Wallet</b>
The wallet is assumed to be a Web application with a wallet backend, maybe implemented as a PWA so it has some offline capabilities and can be installed in the device, providing a user experience similar to a native application. Private key management and most sensitive operations are performed in a backend server, operated by an entity trusted by the end user. Other profiles can support native and completely offline PWA mobile applications, for end users.
This type of wallet supports natural persons, juridical persons and natural persons who are legal entity representatives of juridical persons. For juridical persons the wallet is usually called an `enterprise wallet` but we will use here just the term `wallet` unless the distinction is required.
In this profile we assume that the wallet is not previously registered with the Issuer and that the wallet does not expose public endpoints that are called by the Issuer, even if the wallet has a backend server that could implement those endpoints. That makes the wallet implementations in this profile to be very similar in interactions to a full mobile implementation, making migration to a full mobile implementation easier.
In other words, from the point of view of the Issuer, the wallet in this profile is almost indistinguishable from a full mobile wallet.
<b>User Laptop</b>
For clarity of exposition, we assume in this profile that the End User starts the interactions with the Issuer with an internet browser (user agent) in her laptop. However, there is nothing in the interactions which limits those interactions to a laptop form factor and the End User can interact with any internet browser in any device (mobile, tablet, kiosk).
<b>Issuer</b>
In this profile we assume that the Issuer is composed of two components:
<ul>
- Authorization server: the backend component implementing the existing authentication/authorization functionalities for the Issuer entity.
- Issuer backend: the main server implementing the business logic as a web application and additional backend APIs required for issuance of credentials.
The Issuer backend and the Authorization server could be implemented as a single component in a real use case, but we assume here that they are separated to make the profile more general, especially for big entities and also when using Trust Service Providers for cloud signature and credential issuance, for example.
<b>Authentication of End User and previous Issuer-End User relationship</b>
We assume that the Issuer and End User have a previous relationship and that the Issuer has performed the KYC required by regulation and needed to be able to issue Verifiable Credentials attesting some attributes about the End User. We assume that there is an existing trusted authentication mechanism (not necessarily related to Verifiable Credentials) that the End User employs to access protected resources from the Issuer. For example, the user is an employee or a customer of the Issuer, or the Issuer is a Local Administration and the End User is a citizen living in that city.
<section>Authentication
<figure #iss-authentication>
<img src="images/issuance/issuance_authentication.svg" alt="" />
<figcaption>Issuance authentication.
Before requesting a new credential, the End User has to authenticate with the Issuer with whatever mechanism is already implemented by the Issuer. This profile does not require that it is based on OIDC, Verifiable Credentials or any other specific mechanism.
The level of assurance (LoA) of this authentication mechanism is one of the factors that will determine the confidence that the Verifiers can have on the credentials received by them from a given Issuer.
<x-note>LEARCredential
In the case of the LEARCredential, the End User (John Doe) is an employee of GoodAir and in order to receive the credential John first has to authenticate into the company systems using whatever mechanism GoodAir uses for employee authentication.
Being a modern company, GoodAir uses Verifiable Credentials IAM but this is not a requirement for the issuance of the LEARCredential.
<section>Credential Offer
<figure #iss-credentialoffer>
<img src="images/issuance/issuance_credentialoffer.svg" alt="" />
<figcaption>Credential offer.
In this profile the wallet does not have to implement the Credential Offer Endpoint described in section 4 of [[OpenID.VCI]].
Instead, the Credential Issuer renders a QR code containing a reference to the Credential Offer that can be scanned by the End-User using a Wallet, as described in section 4.1 of [[OpenID.VCI]].
According to the spec, the Credential Offer object is a JSON object containing the Credential Offer parameters and can be sent by value or by reference. To avoid problems with the size of the QR travelling in the URL, this profile requires that the QR contains the `credential_offer_uri`, which is a URL using the `https` scheme referencing a resource containing a JSON object with the Credential Offer parameters. The `credential_offer_uri` endpoint should be implemented by the Issuer backend.
<section>Credential Offer Parameters
This profile restricts the options available in section 4.1.1 of [[OpenID.VCI]]. The profile defines a Credential Offer object containing the following parameters:
<ul>
- `credential_issuer`: REQUIRED. The URL of the Credential Issuer that will be used by the Wallet to obtain one or more Credentials.
- `credentials`: REQUIRED. A JSON array, where every entry is a JSON string. To achieve interoperability faster, this profile defines a global Trusted Credential Schemas List where well-known credential schemas are defined, in addition to the individual credentials that each Issuer can define themselves. The string value MUST be one of the id values in one of the objects in the `credentials_supported` metadata parameter of the Trusted Credential Schemas List (described later), or one of the id values in one of the objects in the `credentials_supported` Credential Issuer metadata parameter provided by the Credential Issuer. When processing, the Wallet MUST resolve this string value to the respective object. The credentials defined in the global Trusted Credential Schema List have precedence over the ones defined by the Credential Issuer.
<x-note>LEARCredential
The only credential being offered in our case is the LEARCredential, so this is the credential schema that should be specified here. The LEARCredential is a credential known globally to the DOME ecosystem, so its schema should be published and be available in the Trusted Credential Schemas List.
- `grants`: REQUIRED. A JSON object indicating to the Wallet the Grant Type `pre-authorized_code`. This grant is represented by a key and an object, where the key is `urn:ietf:params:oauth:grant-type:pre-authorized_code`. In this profile the credential issuance flow requires initial authentication of the End User by the Credential Issuer, so the Pre-Authorized Code Flow achieves a good level of security and we do not need the more general Authorization Code Flow.
In other scenarios like when the wallet is a native mobile application and the user interacts with the Issuer exclusively with the mobile (without the laptop), then the Authorization Code Flow has to be used. This can be described in detail in a different profile.
The grant object contains the following values:
<ul>
- `pre-authorized_code`: REQUIRED. The code representing the Credential Issuer's authorization for the Wallet to obtain Credentials of a certain type. This code MUST be short lived and single-use. This parameter value MUST be included in the subsequent Token Request with the Pre-Authorized Code Flow.
- `user_pin_required`: REQUIRED. The [[OpenID.VCI]] standard says it is RECOMMENDED, but this profile specifies the user pin to achieve a greater level of security. This field is a boolean value specifying whether the Credential Issuer expects presentation of a user PIN along with the Token Request in a Pre-Authorized Code Flow. Default is false. This PIN is intended to bind the Pre-Authorized Code to a certain transaction in order to prevent replay of this code by an attacker that, for example, scanned the QR code while standing behind the legit user. It is RECOMMENDED to send a PIN via a separate channel. The PIN value MUST be sent in the `user_pin` parameter with the respective Token Request.
The following non-normative example shows a Credential Offer object where the Credential Issuer offers the issuance of one Credential ("LEARCredential"):
<x-code .json>
{
"credential_issuer": "https://www.goodair.com",
"credentials": [
"LEARCredential"
],
"grants": {
"urn:ietf:params:oauth:grant-type:pre-authorized_code": {
"pre-authorized_code": "asju68jgtyk9ikkew",
"user_pin_required": true
}
}
}
<section>Contents of the QR code
Below is a non-normative example of the Credential Offer displayed by the Credential Issuer as a QR code when the Credential Offer is passed by reference, as required in this profile:
<x-code .INI>
https://www.goodair.com/credential-offer?
credential_offer_uri=https%3A%2F%2Fserver%2Eexample%2Ecom%2Fcredential-offer%2F5j349k3e3n23j
Which in plain text would be:
<x-code .INI>
https://www.goodair.com/credential-offer?
credential_offer_uri=https://www.goodair.com/credential-offer/5j349k3e3n23j
To increase security, the Issuer MUST make sure that every Credential Offer URI is unique for all credential offers created. This is the purpose of the nonce (`5j349k3e3n23j`) at the end of the url in the example. Issuers can implement whatever mechanism they wish, as far as it is transparent to the wallet.
<section>Credential Issuer Metadata
The Wallet backend retrieves the Credential Issuer's configuration using the Credential Issuer Identifier that was received in the Credential Offer.
A Credential Issuer is identified in this context by a case sensitive URL using the https scheme that contains scheme, host and, optionally, port number and path components, but no query or fragment components. No DID is used in this context.
Credential Issuers MUST make a JSON document available at the path formed by concatenating the string `/.well-known/openid-credential-issuer` to the Credential Issuer Identifier. If the Credential Issuer value contains a path component, any terminating / MUST be removed before appending `/.well-known/openid-credential-issuer`.
`openid-credential-issuer` MUST point to a JSON document compliant with this specification and MUST be returned using the `application/json` content type.
The retrieval of the Credential Issuer configuration is illustrated below.
<figure #iss-issuermetadata>
<img src="images/issuance/issuance_issuermetadata.svg" alt="" />
<figcaption>Issuer metadata.
<section>Credential Issuer Metadata Parameters
The object contained in `openid-credential-issuer` contains the following:
<ul>
- `credential_issuer`: REQUIRED. The Credential Issuer's identifier.
- `credential_endpoint`: REQUIRED. URL of the Credential Issuer's Credential Endpoint. This URL MUST use the https scheme and MAY contain port, path and query parameter components.
- `credentials_supported`: REQUIRED. A JSON array containing a list of JSON objects, each of them representing metadata about a separate credential type that the Credential Issuer can issue. The JSON objects in the array MUST conform to the structure of the Section XXXX.
TODO: define a global directory of credentials supported to eliminate requirement for each individual Issuer to publish its own list.
This profile does not make use of the following parameters:
<ul>
- `authorization_server` parameter, because it uses the `pre-authorized_code` Grant type.
- `batch_credential_endpoint` parameter. It indicates that the Credential Issuer does not support the Batch Credential Endpoint.
- `display` parameter.
<section>OAuth 2.0 Authorization Server Metadata
This specification also defines a new OAuth 2.0 Authorization Server metadata [[RFC8414]] parameter to publish whether the AS that the Credential Issuer relies on for authorization, supports anonymous Token Requests with the Pre-authorized Grant Type. It is defined as follows:
<ul>
- `pre-authorized_grant_anonymous_access_supported`: OPTIONAL. A JSON Boolean indicating whether the issuer accepts a Token Request with a Pre-Authorized Code but without a client id. The default is false.
<section>Access Token
<figure #issuance_accesstoken>
<img src="images/issuance/issuance_accesstoken.svg" alt="" />
<figcaption>Access Token.
The Wallet invokes the Token Endpoint implemented by the Authorization Server, which issues an Access Token and, optionally, a Refresh Token in exchange for the Pre-authorized Code that the wallet obtained in the Credential Offer.
<section>Token Request
After the wallet receives the Credential Issuer Metadata, a Token Request is made as defined in Section 4.1.3 of [[RFC6749]].
The following are the extension parameters to the Token Request used in a Pre-Authorized Code Flow as used in this profile:
<ul>
- `pre-authorized_code`: REQUIRED. The code representing the authorization to obtain Credentials of a certain type.
- `user_pin`: OPTIONAL. String value containing a user PIN. This value MUST be present if user_pin_required was set to true in the Credential Offer. The string value MUST consist of maximum 8 numeric characters (the numbers 0 - 9).
In this profile the Wallet does not have to authenticate when using the Token Endpoint, because we are using the Pre-Authorized Code Grant Type, given the level of trust between the Issuer and the End User and that authentication was already performed at the beginning of the flow.
Below is a non-normative example of a Token Request:
<x-code .HTTP>
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code
&pre-authorized_code=SplxlOBeZQQYbYS6WxSbIA
&user_pin=493536
<section>Successful Token Response
Token Responses are made as defined in [[RFC6749]].
In addition to the response parameters defined in [[RFC6749]], the Authorization Server returns the following parameters:
<ul>
- `c_nonce`: REQUIRED. JSON string containing a nonce to be used to create a proof of possession of key material when requesting a Credential. The Wallet MUST use this nonce value for its subsequent credential requests until the Credential Issuer provides a fresh nonce.
- `c_nonce_expires_in`: REQUIRED. JSON integer denoting the lifetime in seconds of the c_nonce.
Below is a non-normative example of a Token Response:
<x-code .HTTP>
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp..sHQ",
"token_type": "bearer",
"expires_in": 86400,
"c_nonce": "tZignsnFbp",
"c_nonce_expires_in": 86400
}
<section>Token Error Response
If the Token Request is invalid or unauthorized, the Authorization Server constructs the error response as defined in section 6.3 of [[OpenID.VCI]].
<section>Request and receive Credential
<figure #issuance_requestcredential>
<img src="images/issuance/issuance_requestcredential.svg" alt="" />
<figcaption>Request and receive Credential.
The Wallet backend invokes the Credential Endpoint, which issues a Credential as approved by the End-User upon presentation of a valid Access Token representing this approval.
Communication with the Credential Endpoint MUST utilize TLS.
The client can request issuance of a Credential of a certain type multiple times, e.g., to associate the Credential with different public keys/Decentralized Identifiers (DIDs) or to refresh a certain Credential.
If the Access Token is valid for requesting issuance of multiple Credentials, it is at the client's discretion to decide the order in which to request issuance of multiple Credentials requested in the Authorization Request.
<section>Binding the Issued Credential to the identifier of the End-User possessing that Credential
The Issued Credential MUST be cryptographically bound to the identifier of the End-User who possesses the Credential. Cryptographic binding allows the Verifier to verify during the presentation of a Credential that the End-User presenting a Credential is the same End-User to whom that Credential was issued.
The Wallet has to provide proof of control alongside key material using the mechanism described below.
<section>Credential Request
The Wallet backend makes a Credential Request to the Credential Endpoint by sending the following parameters in the entity-body of an HTTP POST request using the `application/json` media type.
<ul>
- `format`: REQUIRED. This profile uses the Credential format identifier `jwt_vc_json`.
- `proof`: OPTIONAL. JSON object containing proof of possession of the key material the issued Credential shall be bound to. The specification envisions use of different types of proofs for different cryptographic schemes. The proof object MUST contain a `proof_type` claim of type JSON string denoting the concrete proof type. This type determines the further claims in the proof object and its respective processing rules. Proof types are defined in Section [[[#proof_type]]].
The proof element MUST incorporate a `c_nonce` value generated by the Credential Issuer and the Credential Issuer Identifier (audience) to allow the Credential Issuer to detect replay. The way that data is incorporated depends on the proof type. In a JWT, for example, the `c_nonce` is conveyed in the `nonce` claim whereas the audience is conveyed in the `aud` claim. In a Linked Data proof, for example, the `c_nonce` is included as the challenge element in the proof object and the Credential Issuer (the intended audience) is included as the domain element.
<section #proof_type>Proof Type
This specification defines only one value for `proof_type`:
`jwt`: objects of this type contain a single jwt element with a JWS [[RFC7515]] as proof of possession. The JWT MUST contain the following elements:
<ul>
- in the JOSE Header,
<ul>
- `typ`: REQUIRED. MUST be `openid4vci-proof+jwt`, which explicitly types the proof JWT as recommended in Section 3.11 of [[RFC8725]].
- `alg`: REQUIRED. A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. MUST NOT be none or an identifier for a symmetric algorithm (MAC).
- `kid`: REQUIRED. JOSE Header containing the key ID. The Credential will be bound to a DID, so the kid refers to a DID URL which identifies a particular key in the DID Document that the Credential will be bound to.
- in the JWT body,
<ul>
- `aud`: REQUIRED (string). The value of this claim MUST be the Credential Issuer URL of the Credential Issuer.
- `iat`: REQUIRED (number). The value of this claim MUST be the time at which the proof was issued using the syntax defined in [[RFC7519]].
- `nonce`: REQUIRED (string). The value type of this claim MUST be a string, where the value is the `c_nonce` provided by the Credential Issuer.
The Credential Issuer MUST validate that the proof is actually signed by a key identified in the JOSE Header.
Below is a non-normative example of a proof parameter (dots in the middle of jwt for display purposes only), for the example of issuing a LEARCredential:
<x-code .json>
{
"proof_type": "jwt",
"jwt": "eyJraWQiOiJkaWQ6ZXhhb....aZKPxgihac0aW9EkL1nOzM"
}
where the JWT looks like this:
<x-code .json>
{
"typ": "openid4vci-proof+jwt",
"alg": "ES256",
"kid":"did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
}
{
"iss": "s6BhdRkqt3",
"aud": "https://www.goodair.com",
"iat": 1659145924,
"nonce": "tZignsnFbp"
}
In the example of a LEARCredential, the wallet generates a pair of public/private keys and a `did:key` identifier which is univocally related to the public key. This is the reason why the `kid` field above is exactly the DID identifier under this DID method. The `did:key` method is very simple and achieves a very high degree of privacy, allowing the creation of many different identifiers which can be one-use only if so desired.
The `did:key` method is perfect for the requirements of our usage of the LEARCredential. Any other suitable DID method can be used if it is required, but this is out of scope for this profile.
<section>Credential Response
This profile restricts Credential Response to be Synchronous and Deferred response is not used. The Credential Issuer MUST be able to immediately issue a requested Credential and send it to the Client.
The following claims are used in the Credential Response:
<ul>
- `format`: REQUIRED. JSON string denoting the format of the issued Credential. This profile uses the format identifier `jwt_vc_json`.
- `credential`: REQUIRED. Contains issued Credential. MUST be a JSON string.
- `c_nonce`: OPTIONAL. JSON string containing a nonce to be used to create a proof of possession of key material when requesting a Credential. When received, the Wallet MUST use this nonce value for its subsequent credential requests until the Credential Issuer provides a fresh nonce.