-
Notifications
You must be signed in to change notification settings - Fork 4
/
openid-federation-1_0.xml
11006 lines (10591 loc) · 431 KB
/
openid-federation-1_0.xml
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
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type='text/xsl' href='http://xml2rfc.tools.ietf.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc PUBLIC "-//IETF//DTD RFC 2629//EN"
"http://xml2rfc.tools.ietf.org/authoring/rfc2629.dtd">
<!--
NOTE: This XML file is input used to produce the authoritative copy of an
OpenID Foundation specification. The authoritative copy is the HTML output.
This XML source file is not authoritative. The statement ipr="none" is
present only to satisfy the document compilation tool and is not indicative
of the IPR status of this specification. The IPR for this specification is
described in the "Notices" section. This is a public OpenID Foundation
document and not a private document, as the private="..." declaration could
be taken to indicate.
-->
<rfc category="std" docName="openid-federation-1_0" ipr="none" xmlns:xi="http://www.w3.org/2001/XInclude">
<?rfc toc="yes" ?>
<?rfc tocdepth="5" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc strict="yes" ?>
<?rfc iprnotified="no" ?>
<?rfc private="Draft" ?>
<front>
<title abbrev="OpenID Federation">OpenID Federation 1.0 -
draft 40
</title>
<author fullname="Roland Hedberg" initials="R." role="editor"
surname="Hedberg">
<organization>independent</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization abbrev="Self-Issued Consulting">Self-Issued Consulting</organization>
<address>
<email>[email protected]</email>
<uri>https://self-issued.info/</uri>
</address>
</author>
<author fullname="Andreas Åkre Solberg" initials="A.Å."
surname="Solberg">
<organization>Sikt</organization>
<address>
<email>[email protected]</email>
<uri>https://www.linkedin.com/in/andreassolberg/</uri>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization abbrev="Yubico">Yubico</organization>
<address>
<email>[email protected]</email>
<uri>http://www.thread-safe.com/</uri>
</address>
</author>
<author fullname="Giuseppe De Marco" initials="G." surname="De Marco">
<organization>independent</organization>
<address>
<email>[email protected]</email>
<uri>https://www.linkedin.com/in/giuseppe-de-marco-bb054245/</uri>
</address>
</author>
<author fullname="Vladimir Dzhuvinov" initials="V." surname="Dzhuvinov">
<organization>Connect2id</organization>
<address>
<email>[email protected]</email>
<uri>https://twitter.com/dzhuvi</uri>
</address>
</author>
<date day="24" month="October" year="2024"/>
<workgroup>OpenID Connect Working Group</workgroup>
<keyword>OpenID</keyword>
<keyword>Connect</keyword>
<keyword>Federation</keyword>
<keyword>Multilateral Federation</keyword>
<keyword>Federation Entity</keyword>
<keyword>Federation Operator</keyword>
<keyword>Trust Anchor</keyword>
<keyword>Trust Chain</keyword>
<keyword>Trust Establishment</keyword>
<abstract>
<t>
A federation can be expressed as an agreement between parties that trust each other.
In bilateral federations, direct trust can be established between
two organizations belonging to the same federation.
In a multilateral federation, bilateral agreements might not be practical,
in which case, trust can be mediated by a third party.
That is the model used in this specification.
</t>
<t>
An Entity in the federation must be able to trust that other Entities
it interacts with belong to the same federation.
It must also be able to trust that the information the other Entities
publish about themselves has not been tampered with during transport
and that it adheres to the federation's policies.
</t>
<t>
This specification defines basic components used to build
multilateral federations and describes how to apply them when
the underlying authentication protocol used is OpenID Connect or
the underlying authorization protocol is OAuth 2.0.
However, these components can also be
used for trust establishment with other application protocols.
</t>
</abstract>
</front>
<middle>
<section anchor="Introduction" title="Introduction">
<t>
This specification describes how two Entities that would like to
interact can establish trust between them by means of a trusted third party
called a Trust Anchor.
A Trust Anchor is an Entity whose main purpose is to issue statements
about Entities.
An identity federation can be realized using this specification using
one or more levels of authorities.
Examples of authorities are federation operators, organizations,
departments within organizations, and individual sites.
This
specification provides the basic technical trust infrastructure building
blocks needed to create a dynamic and distributed trust network, such as a
federation.
</t>
<t>
Note that this specification only concerns itself with how Entities
in a federation get to know about each other. An organization MAY
be represented by more than one Entity in a federation. An Entity
MAY also belong to more than one federation. Determining that two
Entities belong to the same federation is the basis for
establishing trust between them in this specification.
</t>
<t>
Of course, the word "trust" is also used in the vernacular to
encompass confidence in the security, reliability, and integrity of entities
and their actions. This kind trust is often established through
empirical proof, such as past performance, security certifications,
or transparent operational practices, which demonstrate a track
record of adherence to security standards and ethical conduct.
To be clear, this broader meaning of trust, while important,
is largely beyond the scope of what this specification accomplishes.
</t>
<figure>
<preamble>
Below is an example of two federations rooted at two different
Trust Anchors with some members in common.
Every Entity is able to establish mutual trust with any
other Entity by means of having at least one
common Trust Anchor between them.
</preamble>
<name>
Two Coexisting Federations with Some Members in Common
</name>
<!--
NOTE: this figure was made with ASCIIflow and its editable sources
are available at the following link:
https://asciiflow.com/#/share/eJzlVb1OwzAQfpXIcwcEA9AtQCQ60FZJ2CyhCIJaCYIUZWhUVUKZGTJEKANjxz4B4mn6JLhpfuzL2XGyMGBFiu3cfd%2F5891lTQLv1Sdj8uw%2F%2BaEXLd%2BCh8WSzcLHRUxG5MWL%2FZB9XlOyomR8eXYxoiRms9PzEzaL%2FFXEFpQYbOyzj3323vNJDWQMQ6I0ODonbbxkKOoWweKIXPvecQ1zen07sw2zJkIjEGyvAJAk4qReK2JXxphVVruuo9YGOaBOGtxM4qJ48jIUeNB6gVKBc%2Fyhcyn95w9M2b4wiTGbY7aa7kD6fKAS1ZaYT83p0M1UBatRV1tjMnUt%2B866mZiuVSEp0xuNSCh1cKeyREdzNG8rBiNsczQu4jaPoyi3XWuSa3I08pSqpJC6eEvaHKIWz5Jh%2BhzJvsWMhWyZYGrPu1TDLktMZpEBN2UM0pJEuMTB4Rc4SRk2UBpFRpEODkKqpgWu6ny2owqSu31OUT31pFiIhgqRMBx9D63WArOzF2yrm3z1RILZ29EsCon1NeAvF8z%2FD4KkZeH11d7VoxD%2BqGIxH16mox8tWlL4NlJOZEM2vypFZos%3D)
-->
<artwork><![CDATA[
.-----------------. .-----------------.
| Trust Anchor A | | Trust Anchor B |
'------.--.-------' '----.--.--.------'
| | | | |
.--' '---. .-------------------' | |
| | | | |
.---v. .-----v-v------. .-----------' |
| OP | | Intermediate | | |
'----' '--.--.--.-----' | .---------v----.
| | | | | Intermediate |
.-------' | '------. | '---.--.--.----'
| | | | | | |
.--v-. .-v--. .v--v. .---' | '----.
| RP | | RS | | OP | | | |
'----' '----' '----' | .--v-. .-v--.
| | RP | | RP |
| '----' '----'
|
.-------v------.
| Intermediate |
'----.--.--.---'
| | |
.-----' | '----.
| | |
.--v-. .--v-. .-v--.
| OP | | RP | | AS |
'----' '----' '----'
]]>
</artwork>
</figure>
<section anchor="requirements-language" title="Requirements Notation and Conventions">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/>.
</t>
<t>
All uses of JSON Web Signature (JWS) <xref target="RFC7515"/>
and JSON Web Encryption (JWE) <xref target="RFC7516"/>
data structures in this specification utilize
the JWS Compact Serialization or the JWE Compact Serialization;
the JWS JSON Serialization and the JWE JSON Serialization are not used.
</t>
</section>
<section anchor="Terminology" title="Terminology">
<t>
This specification uses the terms "Claim",
"Claim Name", "Claim Value", "JSON Web Token (JWT)", and "JWT Claims Set"
defined by <xref target="RFC7519">JSON Web Token (JWT)</xref>,
the terms "OpenID Provider (OP)" and "Relying Party (RP)" defined
by <xref target="OpenID.Core">OpenID Connect Core 1.0</xref>, and
the terms "Authorization Endpoint", "Authorization Server",
"Client", "Client Authentication", "Client Identifier", "Client Secret",
"Grant Type", "Protected Resource", "Redirection URI", "Refresh Token",
and "Token Endpoint"
defined by <xref target="RFC6749">OAuth 2.0</xref>.
</t>
<t>
This specification also defines the following terms:
<list style="hanging">
<t hangText="Entity">
<vspace/>
Something that has a separate and distinct existence and that can
be identified in a context.
</t>
<t hangText="Entity Identifier">
<vspace/>
A globally unique URL that is bound to one Entity.
This URL MUST use the <spanx style="verb">https</spanx> scheme,
have a host component, and MAY contain port and path components.
It MUST NOT contain query parameter or fragment components.
</t>
<t hangText="Trust Anchor">
<vspace/>
An Entity that represents a trusted third party.
</t>
<t hangText="Federation Entity">
<vspace/>
An Entity for which it is possible to construct a Trust Chain
from the Entity to a Trust Anchor.
</t>
<t hangText="Entity Statement">
<vspace/>
A signed JWT that contains the information needed
for an Entity to participate in federation(s),
including metadata about itself
and policies that apply to other Entities that it is authoritative for.
</t>
<t hangText="Entity Configuration">
<vspace/>
An Entity Statement issued by an Entity about itself. It contains
the Entity's signing keys and further data used to control the
Trust Chain resolution process, such as authority hints.
</t>
<t hangText="Subordinate Statement">
<vspace/>
An Entity Statement issued by a Superior Entity about
an Entity that is its Immediate Subordinate.
</t>
<t hangText="Entity Type">
<vspace/>
A role and function that an Entity plays
within a federation. An Entity MUST be of at
least one type and MAY be of many types.
For example, an Entity can be both an OpenID Provider
and Relying Party at the same time.
</t>
<t hangText="Entity Type Identifier">
<vspace/>
String identifier for an Entity Type.
</t>
<t hangText="Federation Operator">
An organization that is authoritative for a federation.
A federation operator administers the Trust Anchor(s) for Entities in its federation.
</t>
<t hangText="Intermediate Entity">
<vspace/>
An Entity that issues
an Entity Statement appearing somewhere in between those
issued by the Trust Anchor and the subject of a Trust Chain
(which is typically a Leaf Entity).
The terms Intermediate Entity and Intermediate are used
interchangeably in this specification.
</t>
<t hangText="Leaf Entity">
<vspace/>
An Entity with no Subordinate Entities.
Leaf Entities typically play a protocol role,
such as an OpenID Connect Relying Party or OpenID Provider.
The terms Leaf Entity and Leaf
are used interchangeably in this specification.
</t>
<t hangText="Subordinate Entity">
<vspace/>
An Entity that is somewhere below a Superior Entity
(a Trust Anchor or Intermediate) in the trust hierarchy,
possibly with Intermediates between them.
The terms Subordinate Entity and Subordinate
are used interchangeably in this specification.
</t>
<t hangText="Superior Entity">
<vspace/>
An Entity that is somewhere above one or more Entities
(a Leaf or Intermediate) in the trust hierarchy,
possibly with Intermediates between them.
The terms Superior Entity and Superior
are used interchangeably in this specification.
</t>
<t hangText="Immediate Subordinate Entity">
<vspace/>
An Entity that is immediately below a Superior Entity
in the trust hierarchy, with no Intermediates between them.
The terms Immediate Subordinate Entity and Immediate Subordinate
are used interchangeably in this specification.
</t>
<t hangText="Immediate Superior Entity">
<vspace/>
An Entity that is immediately above one or more Subordinate Entities
in the trust hierarchy, with no Intermediates between them.
The terms Immediate Superior Entity and Immediate Superior
are used interchangeably in this specification.
</t>
<t hangText="Federation Entity Discovery">
<vspace/>
A process that starts with the Entity Identifier
for the subject of the Trust Chain and collects
Entity Statements until the chosen Trust Anchor is reached.
From the collected Entity Statements, a Trust Chain
is constructed and verified.
The result of the Federation Entity Discovery is that the
metadata for the Trust Chain subject is constructed from the Trust Chain.
</t>
<t hangText="Trust Chain">
<vspace/>
A sequence of Entity Statements that represents a chain
starting at an Entity Configuration that is the subject of the chain
(typically of a Leaf Entity) and ending in a Trust Anchor.
</t>
<t hangText="Trust Mark">
Statement of conformance to a
well-scoped set of trust and/or interoperability requirements
as determined by an accreditation authority.
</t>
<t hangText="Federation Entity Keys">
Keys used for the cryptographic signatures required by
the trust mechanisms defined in this specification.
Every participant in a Federation publishes its public
Federation Entity Keys in its Entity Configuration.
</t>
</list>
</t>
</section>
</section>
<section title="Overall Architecture" anchor="architecture">
<t>
The basic component is the Entity Statement, which is a cryptographically
signed <xref target="RFC7519">JSON Web Token (JWT)</xref>.
A set of Entity Statements can form a path from an Entity
(typically a Leaf Entity) to
a Trust Anchor. Entity Configurations
issued by Entities about themselves control the Trust Chain
resolution process.
</t>
<t>
The Entity Configuration of a Leaf or Intermediate Entity contains one or more
references to its Immediate Superiors in the
<spanx style="verb">authority_hints</spanx> parameter
described in <xref target="authority_hints"/>.
These references can be used to download the Entity Configuration of each Immediate Superior.
One or more Entity Configurations are traversed during the Federation Entity Discovery
until the Trust Anchor is reached.
</t>
<t>
The Trust Anchor and its Intermediates issue Entity Statements
about their Immediate Subordinate Entities called Subordinate Statements.
The sequence of Entity Configurations
and Subordinate Statements that validate the relationship between
a Superior and a Subordinate, along a path towards the Trust Anchor,
forms the proof that the subject of Trust Chain
(typically a Leaf Entity) is a member of
the federation rooted at the Trust Anchor.
</t>
<t>
The chain that links the statements to one another is verified with
the signature of each statement, as described in <xref target="trust_chain"/>.
</t>
<t>
Once there is a verified Trust Chain, the federation policy is applied
and the metadata for the Trust Chain subject
within the Federation is derived,
as described in <xref target="federation_policy"/>.
</t>
<t>
This specification deals with trust operations;
it does not cover or touch protocol operations
other than metadata derivation and exchange.
In OpenID Connect terms, these are the protocol operations specified in
<xref target="OpenID.Discovery">OpenID Connect Discovery 1.0</xref>
and
<xref target="OpenID.Registration">OpenID Connect Dynamic Client Registration 1.0</xref>.
</t>
<t>
OpenID Connect is used in many of the examples in this
specification, however this does not mean that this specification can only be used
with OpenID Connect. On the contrary, it can also be
used to build federations for any other protocols.
</t>
<section title="Cryptographic Trust Mechanism" anchor="CryptographicTrustMechanism">
<t>
The objects defined by this specification
that are used to establish cryptographic trust between participants
are secured as signed JWTs using public key cryptography.
In particular, the keys used for securing these objects are managed by
the Entities controlling those objects, with the public keys securing them
being distributed through those objects themselves.
This kind of trust mechanism has been utilized by
research and academic federations for over a decade.
</t>
<t>
Note that this cryptographic trust mechanism intentionally does not rely on
Web PKI / TLS certificates for signing keys.
Which TLS certificates are considered trusted can vary considerably between systems
depending upon which certificate authorities are considered trusted
and there are have been notable examples of ostensibly trusted certificates being compromised.
For those reasons, this specification explicitly eschews reliance on Web PKI
in favor of self-managed public keys, in this case,
keys represented as JSON Web Keys (JWKs) <xref target="RFC7517"/>.
</t>
</section>
</section>
<section anchor="entity-statement" title="Entity Statement">
<t>
An Entity Statement contains the information needed for the Entity
that is the subject of the Entity Statement to participate in federation(s).
An Entity Statement is a signed JWT.
The subject of the JWT is the Entity itself.
The issuer of the JWT is the party that issued the Entity Statement.
All Entities in a federation publish an Entity Statement about themselves
called an Entity Configuration.
Superior Entities in a federation publish Entity Statements about
their Immediate Subordinate Entities called Subordinate Statements.
</t>
<t>
Entity Statement JWTs MUST be explicitly typed, by setting the
<spanx style="verb">typ</spanx> header parameter to
<spanx style="verb">entity-statement+jwt</spanx> to prevent
cross-JWT confusion, per Section 3.11 of <xref target="RFC8725"/>.
Entity Statements without a <spanx style="verb">typ</spanx> header parameter
or with a different <spanx style="verb">typ</spanx> value MUST be rejected.
</t>
<t>
The Entity Statement is signed using one of the private keys of the issuer
Entity in the form of a <xref target="RFC7515">JSON Web Signature
(JWS)</xref>.
Implementations SHOULD support signature verification with
the RSA SHA-256 algorithm because OpenID Connect Core
requires support for it (<spanx style="verb">alg</spanx>
value of <spanx style="verb">RS256</spanx>).
Federations MAY also specify different mandatory-to-implement algorithms.
</t>
<t>
Entity Statement JWTs MUST include the
<spanx style="verb">kid</spanx> (Key ID) header parameter
with its value being the Key ID of the signing key used.
</t>
<t>
The claims in an Entity Statement are:
</t>
<t>
<list style="hanging">
<t hangText="iss">
<vspace/>
REQUIRED. The Entity Identifier of the issuer of
the Entity Statement.
If the <spanx style="verb">iss</spanx> and
the <spanx style="verb">sub</spanx> are identical,
the issuer is making an Entity Statement about itself
called an Entity Configuration.
</t>
<t hangText="sub">
<vspace/>
REQUIRED. The Entity Identifier of the subject.
</t>
<t hangText="iat">
<vspace/>
REQUIRED. Number. Time when this statement was issued.
This is expressed as Seconds Since the Epoch, as defined in
<xref target="RFC7519"/>.
</t>
<t hangText="exp">
<vspace/>
REQUIRED. Number.
Expiration time after which the statement MUST NOT be
accepted for processing. This is expressed as Seconds
Since the Epoch, as defined in <xref target="RFC7519"/>.
</t>
<t hangText="jwks">
<vspace/>
REQUIRED. A <xref target="RFC7517">JSON Web Key Set (JWKS)</xref>
representing the public part of the subject's Federation Entity
signing keys. The corresponding private key is
used by the Entity to sign the Entity Configuration about itself,
by Trust Anchors and Intermediate Entities
to sign Subordinate Statements about their Immediate Subordinates,
and for other signatures made by Federation Entities,
such as Trust Mark signatures.
This claim is only OPTIONAL for the Entity Statement returned
from an OP when the client is doing Explicit Registration;
in all other cases, it is REQUIRED.
Every JWK in the JWK Set MUST have a unique <spanx style="verb">kid</spanx> (Key ID) value.
It is RECOMMENDED that the Key ID be the JWK Thumbprint <xref target="RFC7638"/>
using the SHA-256 hash function of the key.
<vspace blankLines="1"/>
These Federation Entity Keys SHOULD NOT be used in other protocols.
(Keys to be used in other protocols, such as OpenID Connect,
are conveyed in the <spanx style="verb">metadata</spanx> elements
for the protocol's Entity Type Identifiers,
such as the metadata under the
<spanx style="verb">openid_provider</spanx> and
<spanx style="verb">openid_relying_party</spanx>
Entity Type Identifiers.)
</t>
<t hangText="authority_hints" anchor="authority_hints">
<vspace/>
OPTIONAL. An array of strings representing
the Entity Identifiers of Intermediate Entities or Trust Anchors
that are Immediate Superiors of the Entity.
This claim is REQUIRED in Entity Configurations of
the Entities that have at least one Superior above them,
such as Leaf and Intermediate Entities.
Its value MUST contain the Entity Identifiers of
its Immediate Superiors and
MUST NOT be the empty array
<spanx style="verb">[]</spanx>.
This claim MUST NOT be present in Entity Configurations
of Trust Anchors with no Superiors.
It MUST NOT be present in Subordinate Statements.
</t>
<t hangText="metadata">
<vspace/>
OPTIONAL. JSON object that represents the Entity's Types and the
metadata for those Entity Types. Each member name of the JSON
object is an Entity Type Identifier, and each value MUST be a JSON
object containing metadata parameters according to the metadata
schema of the Entity Type.
<vspace blankLines="1" />
When an Entity participates in a federation or federations with
one or more Entity Types, its Entity Configuration MUST contain a
<spanx style="verb">metadata</spanx> claim with JSON object values
for each of the corresponding Entity Type Identifiers, even if the
values are the empty JSON object <spanx style="verb">{}</spanx>
(when the Entity Type has no associated metadata or Immediate
Superiors supply any needed metadata).
<vspace blankLines="1"/>
An Immediate Superior MAY provide selected or all metadata
parameters for an Immediate Subordinate, by using the
<spanx style="verb">metadata</spanx> claim in a Subordinate
Statement. When <spanx style="verb">metadata</spanx> is used in a
Subordinate Statement, it applies only to those Entity Types that
are present in the subject's Entity Configuration. Furthermore,
the metadata applies only to the subject of the Subordinate
Statement and has no effect on the subject's Subordinates.
Metadata parameters in a Subordinate Statement have precedence and
override identically named parameters under the same Entity Type
in the subject's Entity Configuration. If both
<spanx style="verb">metadata</spanx> and
<spanx style="verb">metadata_policy</spanx> appear in a
Subordinate Statement, then the stated
<spanx style="verb">metadata</spanx> MUST be applied before the
<spanx style="verb">metadata_policy</spanx>, as described in
<xref target="metadata_policy_application"/>.
</t>
<t hangText="metadata_policy">
<vspace/>
OPTIONAL. JSON object that defines a metadata policy, as described
in <xref target="metadata_policy"/>. Only Subordinate Statements
MAY include this claim. The metadata policy applies to the Entity
that is the subject of this Subordinate Statement as well as to
all Entities that are Subordinate to it. Applying to Subordinate
Entities distinguishes <spanx style="verb">metadata_policy</spanx>
from <spanx style="verb">metadata</spanx>, which only applies to
the subject itself.
</t>
<t hangText="constraints">
<vspace/>
OPTIONAL. JSON object that defines Trust Chain constraints, as
described in <xref target="chain_constraints"/>. Only Subordinate
Statements MAY include this claim. The constraints apply to the
Entity that is the subject of this Subordinate Statement as well
as to all Entities that are Subordinate to it.
</t>
<t hangText="crit">
<vspace/>
OPTIONAL.
Entity Statements require that
the <spanx style="verb">crit</spanx> (critical) claim
defined in <xref target="critClaim"/> be understood and processed.
Claims in the Entity Statement whose claim names are in the array
that is the value of this claim MUST be understood and processed.
Claims specified for use in Entity Statements by this specification
MUST NOT be included in the list.
</t>
<t hangText="metadata_policy_crit">
<vspace/>
OPTIONAL.
Array of strings specifying critical metadata policy operators
other than the standard ones defined in
<xref target="standard_metadata_policy_operators"/> that MUST be
understood and processed. Only Subordinate Statements MAY include
this claim and when included its value MUST NOT be the empty array
<spanx style="verb">[]</spanx>. If any of the listed policy
operators are not understood and supported, then the Subordinate
Statement and thus the Trust Chain that includes it MUST be
considered invalid.
</t>
<t hangText="trust_marks">
<vspace/>
OPTIONAL. An array of JSON objects, each representing
a Trust Mark.
Each JSON object MUST contain the following two claims
and MAY contain other claims. All the claims in the
JSON object MUST have the same values as those
contained in the Trust Mark JWT.
<list style="hanging">
<t hangText="id">
The Trust Mark identifier.
It MUST be the same value as the
<spanx style="verb">id</spanx>
claim contained in the
Trust Mark JWT.
</t>
<t hangText="trust_mark">
A signed JSON Web Token that represents a Trust Mark.
</t>
</list>
Trust Marks are described in <xref target="trust_marks"/>.
This claim SHOULD only be used in Entity Configurations.
</t>
<t hangText="trust_mark_issuers">
<vspace/>
OPTIONAL.
A Trust Anchor MAY use this claim to tell which combination of
Trust Mark identifiers and issuers are trusted by the federation.
This claim MUST be ignored if present in an Entity Configuration
for an Entity that is not a Trust Anchor.
It is a JSON object with member names that are Trust Mark identifiers and
each corresponding value being an array of Entity Identifiers
that are trusted to represent the accreditation authority
for Trust Marks with that identifier.
If the array following a Trust Mark identifier is empty,
anyone MAY issue Trust Marks with that identifier.
This claim MUST NOT be present in Subordinate Statements.
Trust Marks are described in <xref target="trust_marks"/>.
</t>
<t hangText="trust_mark_owners">
<vspace/>
OPTIONAL.
If a Federation Operator knows that a Trust Mark identifier is owned
by an Entity different from the Trust Mark issuer, then that
knowledge MUST be expressed in this claim.
This claim MUST be ignored if present in an Entity Configuration
for an Entity that is not a Trust Anchor.
It is a JSON object with member names that are Trust Mark identifiers and
each corresponding value being a JSON object with these members:
<list style="hanging">
<t hangText="sub">
<vspace/>
REQUIRED
Identifier of the Trust Mark owner.
</t>
<t hangText="jwks">
<vspace/>
REQUIRED
<xref target="RFC7517">JSON Web Key Set (JWKS)</xref>
containing the owner's Federation Entity Keys used for signing.
</t>
</list>
Other members MAY also be defined and used.
This claim MUST NOT be present in Subordinate Statements.
</t>
<t hangText="source_endpoint">
<vspace/>
OPTIONAL. String containing the fetch endpoint URL
from which the Entity Statement was issued,
as specified in <xref target="fetch_endpoint"/>.
This parameter enables an optimized refresh of the Subordinate Statements
and hence the Trust Chain, by skipping the
request to the Entity Configuration
that is normally required to discover the
<spanx style="verb">federation_fetch_endpoint</spanx>
of the issuing authority.
If an Entity Statement cannot be retrieved from the
<spanx style="verb">source_endpoint</spanx>,
which can occur if the endpoint URL has changed,
the current <spanx style="verb">federation_fetch_endpoint</spanx>
location can be determined by retrieving
the Entity Configuration of the issuer.
</t>
</list>
</t>
<t>
Applications and protocols utilizing Entity Statements MAY specify
and use additional claims.
</t>
<figure>
<preamble>
The following is a non-normative example of the JWT Claims Set for an Entity Statement.
The example contains
a critical extension <spanx style="verb">jti</spanx> (JWT ID) to the
Entity Statement and one critical extension to the policy language
<spanx style="verb">regexp</spanx>
(Regular expression).
</preamble>
<name>
Example Entity Statement JWT Claims Set
</name>
<artwork><![CDATA[
{
"iss": "https://feide.no",
"sub": "https://ntnu.no",
"iat": 1516239022,
"exp": 1516298022,
"jwks": {
"keys": [
{
"kty": "RSA",
"alg": "RS256",
"use": "sig",
"kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
"n": "pnXBOusEANuug6ewezb9J_...",
"e": "AQAB"
}
]
},
"metadata": {
"openid_provider": {
"issuer": "https://ntnu.no",
"organization_name": "NTNU"
},
"oauth_client": {
"organization_name": "NTNU"
}
},
"metadata_policy": {
"openid_provider": {
"id_token_signing_alg_values_supported":
{"subset_of": ["RS256", "RS384", "RS512"]},
"op_policy_uri": {
"regexp":
"^https:\/\/[\\w-]+\\.example\\.com\/[\\w-]+\\.html"}
},
"oauth_client": {
"grant_types": {
"one_of": ["authorization_code", "client_credentials"]
}
}
},
"constraints": {
"max_path_length": 2
},
"crit": ["jti"],
"metadata_policy_crit": ["regexp"],
"source_endpoint": "https://feide.no/federation_api/fetch",
"jti": "7l2lncFdY6SlhNia"
}
]]></artwork>
</figure>
<figure>
<preamble>
The following is a non-normative example of
a <spanx style="verb">trust_mark_owners</spanx> claim value:
</preamble>
<name>
Example <spanx style="verb">trust_mark_owners</spanx> Claim Value
</name>
<artwork><![CDATA[
{
"https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf":
{
"sub": "https://refeds.org/sirtfi",
"jwks" : {
"keys": [
{
"alg": "RS256",
"e": "AQAB",
"kid": "key1",
"kty": "RSA",
"n": "pnXBOusEANuug6ewezb9J_...",
"use": "sig"
}
]
}
}
}
]]></artwork>
</figure>
<figure>
<preamble>
The following is a non-normative example of
a <spanx style="verb">trust_mark_issuers</spanx> claim value:
</preamble>
<name>
Example <spanx style="verb">trust_mark_issuers</spanx> Claim Value
</name>
<artwork><![CDATA[
{
"https://openid.net/certification/op": [],
"https://refeds.org/wp-content/uploads/2016/01/Sirtfi-1.0.pdf":
["https://swamid.se"]
}
]]></artwork>
</figure>
</section>
<section title="Trust Chain" anchor="trust_chain">
<t>
Entities whose statements build a Trust Chain are categorized as:
<list style="hanging">
<t hangText="Trust Anchor">
<vspace/>
An Entity that represents a trusted third party.
</t>
<t hangText="Leaf">
<vspace/>
In an OpenID Connect identity federation, an RP or an OP,
or in an OAuth 2.0 federation, a Client, Authorization Server, or Protected Resource.
</t>
<t hangText="Intermediate">
<vspace/>
Neither a Leaf Entity nor a Trust Anchor.
</t>
</list>
</t>
<t>
A Trust Chain begins with an Entity Configuration
that is the subject of the Trust Chain,
which is typically a Leaf Entity.
The Trust Chain has zero or more Subordinate Statements
issued by Intermediates about their Immediate Subordinates,
and includes the Subordinate Statement issued by the
Trust Anchor about the top-most Intermediate
(if there are Intermediates) or the Trust Chain subject
(if there are no Intermediates).
The Trust Chain logically always ends with the
Entity Configuration of the Trust Anchor,
even though it MAY be omitted from
the JSON array representing the Trust Chain in some cases.
</t>
<t>
The Trust Chain contains the configuration of the federation
as it applies to the Trust Chain subject
at the time of the evaluation of the chain.
</t>
<t>
A simple example: If we have an RP that belongs to Organization A
that is a member of Federation F, the Trust Chain for such a setup
will contain the following Entity Statements:
<list style="numbers">
<t>
an Entity Configuration about the RP published by itself,
</t>
<t>
a Subordinate Statement about the RP published by Organization A,
</t>
<t>
a Subordinate Statement about Organization A published by the Trust Anchor for F,
</t>
<t>
an Entity Configuration about the Trust Anchor for F published by itself.
</t>
</list>
</t>
<t>
Let us refer to the Entity Statements in the Trust Chain as
ES[j], where j = 0,...,i,
with 0 being the index of the first Entity Statement
and i being the zero-based index of the last.
Then:
<list style="symbols">
<t>
ES[0] (the Entity Configuration of the Trust Chain subject)
is signed using a key in ES[0]["jwks"].
</t>
<t>
The <spanx style="verb">iss</spanx> claim in an Entity Statement
is equal to the <spanx style="verb">sub</spanx> claim in the next.
Restating this symbolically,
for each j = 0,...,i-1,
ES[j]["iss"] == ES[j+1]["sub"].
</t>
<t>
An Entity Statement is signed using a key from
the <spanx style="verb">jwks</spanx> claim in the next.
Restating this symbolically,
for each j = 0,...,i-1,
ES[j] is signed by a key in ES[j+1]["jwks"].
</t>
<t>
ES[i] (the Trust Anchor's Entity Configuration in the Trust Chain)
is signed using a key in ES[i]["jwks"].
</t>
</list>
</t>
<t>
The Trust Anchor's public keys are used to verify the signatures on
ES[i] (the Trust Anchor's Entity Configuration) and
ES[i-1] (the Trust Anchor's Subordinate Statement about its
Immediate Subordinate in the Trust Chain).
The Trust Anchor's public keys are distributed
to Entities that need to verify a
Trust Chain in some secure out-of-band way not described in this
document.
</t>
<section title="Beginning and Ending Trust Chains"
anchor="trust-chain-ends">
<t>
A Trust Chain begins with the Entity Configuration of an Entity
for which trust is being established.
This is the subject of the Trust Chain.
This Entity typically plays a protocol role,
such as being an OpenID Provider or OpenID Relying Party.
</t>
<t>
While such Entities are typically Leaf Entities,
other topologies are possible.
For instance, an Entity might simultaneously be an OpenID Provider
and an Intermediate Entity, with OpenID Relying Parties
and/or other Intermediates being Subordinate to it.
This is a case in which the subject of a Trust Chain
would not be a Leaf Entity.
</t>
<t>
A Trust Chain ends with the Entity Configuration of a Trust Anchor.
While Trust Anchors typically have no Superiors,
a Trust Anchor will have a Superior when the Trust Anchor
also acts as an Intermediate Entity in another federation.
This will be the case when there is a hierarchy of federations.
</t>
<t>
Thus, while it is typical for a Trust Chain to end with
a Trust Anchor with no Superiors,
there are situations in which the Trust Chain will end with
a Trust Anchor that nonetheless has Superior Entities.
</t>
</section>
<section title="Trust Chain Example" anchor="trust-chain-example">
<figure>
<preamble>
The following is an example of a Trust Chain consisting of
a Leaf's Entity Configuration and Subordinate Statements issued
by an Intermediate Entity and a Trust Anchor. It shows
the relationship between the three Entities,
their Entity Configurations, and their Subordinate Statements.
The Subordinate Statements are obtained from the
<spanx style="verb">federation_fetch_endpoint</spanx> of
the subject's Immediate Superior. The URL of the
<spanx style="verb">federation_fetch_endpoint</spanx> is
discovered in the Immediate Superior's Entity Configuration.
Note that the first member of the Trust Chain (the Leaf)
is depicted at the bottom of the diagram and that the last
member (the Trust Anchor) is depicted at the top.
</preamble>
<name>