Skip to content

Commit a60cd81

Browse files
selfissuedselfissued
authored
Merge pull request #228 from openid/mbj-validation
Define how to validate Entity Statements
2 parents 468f7c8 + ccebc12 commit a60cd81

File tree

1 file changed

+198
-3
lines changed

1 file changed

+198
-3
lines changed

‎openid-federation-1_0.xml‎

Lines changed: 198 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@
7878
</address>
7979
</author>
8080

81-
<date day="25" month="October" year="2025"/>
81+
<date day="2" month="November" year="2025"/>
8282

8383
<workgroup>OpenID Connect Working Group</workgroup>
8484

@@ -761,9 +761,200 @@
761761
This claim is specific to Explicit Registration responses and is not a
762762
general Entity Statement claim.
763763
</t>
764-
</list>
765-
</section>
764+
</list>
765+
</section>
766+
767+
<section anchor="ESValidation" title="Entity Statement Validation">
768+
<t>
769+
Entity Statements MUST be validated in the following manner.
770+
These steps MAY be performed in a different order, provided that
771+
the result - accepting or rejecting the Entity Statement - is the same.
772+
<list style="numbers">
773+
<t>
774+
The Entity Statement MUST be a signed JWT.
775+
</t>
776+
<t>
777+
The Entity Statement MUST have a
778+
<spanx style="verb">typ</spanx> header parameter with the value
779+
<spanx style="verb">entity-statement+jwt</spanx>.
780+
</t>
781+
<t>
782+
The Entity Statement MUST have an
783+
<spanx style="verb">alg</spanx> (algorithm) header parameter
784+
with a value that is an acceptable JWS signing algorithm;
785+
it MUST NOT be <spanx style="verb">none</spanx>.
786+
</t>
787+
<t>
788+
The Entity Identifier of the Entity to which the Entity Statement refers
789+
MUST match the value of the
790+
<spanx style="verb">sub</spanx> (subject) Claim.
791+
</t>
792+
<t>
793+
The Entity Statement MUST have an
794+
<spanx style="verb">iss</spanx> (issuer) Claim
795+
with a value that is a valid Entity Identifier.
796+
</t>
797+
<t>
798+
When the <spanx style="verb">iss</spanx> (issuer) Claim value
799+
matches the <spanx style="verb">sub</spanx> (subject) Claim value,
800+
then the Entity Statement is this Entity's Entity Configuration.
801+
When they do not match, the Entity Statement is a Subordinate Statement.
802+
When the Entity Statement is a Subordinate Statement,
803+
the <spanx style="verb">iss</spanx> Claim value MUST match
804+
one of the values in the
805+
<spanx style="verb">authority_hints</spanx> array
806+
in the Entity Configuration for the Entity whose Entity Identifier
807+
is the value of the <spanx style="verb">sub</spanx> Claim;
808+
otherwise the Federation graph is not well-formed.
809+
</t>
810+
<t>
811+
The current time MUST be after the time represented by the
812+
<spanx style="verb">iat</spanx> (issued at) Claim
813+
(possibly allowing for some small leeway to account for clock skew).
814+
</t>
815+
<t>
816+
The current time MUST be before the time represented by the
817+
<spanx style="verb">exp</spanx> (expiration) Claim
818+
(possibly allowing for some small leeway to account for clock skew).
819+
</t>
820+
<t>
821+
The <spanx style="verb">jwks</spanx> (JWK Set) Claim
822+
MUST be present, with a value that is a valid
823+
JWK Set <xref target="RFC7517"/>.
824+
</t>
825+
<t>
826+
Obtain the Entity Configuration for the issuing Entity -
827+
the Entity with the Issuer Identifer found in the Entity Statement's
828+
<spanx style="verb">iss</spanx> (issuer) Claim.
829+
When the <spanx style="verb">iss</spanx> and
830+
<spanx style="verb">sub</spanx> Claim values match, this is
831+
the Entity Statement being validated itself.
832+
Otherwise, this can be obtained either from a Trust Chain or
833+
by retrieving it as described in
834+
<xref target="federation_configuration"/>.
835+
</t>
836+
<t>
837+
The Entity Statement's
838+
<spanx style="verb">kid</spanx> (Key ID) header parameter value
839+
MUST be a non-zero length string and
840+
MUST exactly match the <spanx style="verb">kid</spanx> value
841+
for a key in the <spanx style="verb">jwks</spanx> (JWK Set) Claim
842+
of the Entity Configuration of the issuing Entity.
843+
</t>
844+
<t>
845+
The Entity Statement's signature MUST validate using
846+
the issuing Entity's key identified by the
847+
<spanx style="verb">kid</spanx> value.
848+
</t>
849+
<t>
850+
If the <spanx style="verb">crit</spanx> Claim is present,
851+
then each array element in this claim's value
852+
MUST be a string representing an Entity Statement claim
853+
that is not defined by this specification
854+
and that claim MUST be understood
855+
and be able to be processed by the implementation.
856+
</t>
857+
<t>
858+
If the <spanx style="verb">authority_hints</spanx> Claim is present,
859+
the Entity Statement MUST be an Entity Configuration.
860+
Verify that its value is syntactially correct,
861+
as specified in <xref target="authority_hints"/>.
862+
Implementations MAY also validate that the Entity is a Subordinate
863+
of each Entity whose Entity Identifier is listed in the
864+
<spanx style="verb">authority_hints</spanx> array.
865+
</t>
866+
<t>
867+
If the <spanx style="verb">metadata</spanx> Claim is present,
868+
verify that its value is syntactially correct,
869+
not using <spanx style="verb">null</spanx> as metadata values,
870+
as specified in <xref target="metadata"/>.
871+
</t>
872+
<t>
873+
If the <spanx style="verb">metadata_policy</spanx> Claim is present,
874+
the Entity Statement be a Subordinate Statement.
875+
Verify that its value is syntactially correct,
876+
as specified in <xref target="metadata_policy"/>.
877+
</t>
878+
<t>
879+
If the <spanx style="verb">metadata_policy_crit</spanx> Claim is present,
880+
the Entity Statement be a Subordinate Statement.
881+
Each array element in this claim's value
882+
MUST be a string representing a Metadata Policy operator
883+
that is not defined by this specification
884+
and that operator MUST be understood
885+
and be able to be processed by the implementation.
886+
</t>
887+
<t>
888+
If the <spanx style="verb">constraints</spanx> Claim is present,
889+
the Entity Statement be a Subordinate Statement.
890+
Verify that its value is syntactically correct,
891+
as specified in <xref target="chain_constraints"/>.
892+
</t>
893+
<t>
894+
If the <spanx style="verb">trust_marks</spanx> Claim is present,
895+
the Entity Statement MUST be an Entity Configuration.
896+
Validate that the syntax of this Claim Value conforms to the
897+
Claim definition.
898+
In particular, for each element of the array that is the Claim value,
899+
validate that there is a <spanx style="verb">trust_mark_type</spanx>
900+
member whose value matches the
901+
<spanx style="verb">trust_mark_type</spanx> Claim value in the
902+
Trust Mark JWT that is the value of the
903+
<spanx style="verb">trust_mark</spanx> member.
904+
Validating the syntax is separate from evaluating whether particular
905+
Trust Marks are issued by a trusted party and are trusted;
906+
that process is described in <xref target="trust-mark-validation"/>
907+
and MAY be performed as a separate step from syntactic validation.
908+
</t>
909+
<t>
910+
If the <spanx style="verb">trust_mark_issuers</spanx> Claim is present,
911+
the Entity Statement MUST be an Entity Configuration.
912+
Validate that its Claim value is a JSON object with
913+
Trust Mark type identifiers as the member names and
914+
arrays of Entity Identifiers as the values.
915+
</t>
916+
<t>
917+
If the <spanx style="verb">trust_mark_owners</spanx> Claim is present,
918+
the Entity Statement MUST be an Entity Configuration.
919+
Validate that its Claim value is a JSON object with
920+
Trust Mark type identifiers as the member names and
921+
values that are JSON objects containing
922+
a <spanx style="verb">sub</spanx> member with a value that is
923+
an Entity Identifier and
924+
a <spanx style="verb">jwks</spanx> member with a value that is
925+
a JSON Web Key Set.
926+
</t>
927+
<t>
928+
If the <spanx style="verb">source_endpoint</spanx> Claim is present,
929+
the Entity Statement MUST be a Subordinate Statement.
930+
Validate that its Claim value is a URL.
931+
Implementations MAY also make a fetch call to the URL
932+
to validate that this is the fetch endpoint
933+
from which the Entity Statement was issued.
934+
</t>
935+
<t>
936+
If the <spanx style="verb">trust_anchor</spanx> Claim is present,
937+
validate that its value is a URL
938+
using the <spanx style="verb">https</spanx> scheme.
939+
Implementations SHOULD validate that the Entity Identifier matches
940+
one of the Trust Anchors configured for the deployment.
941+
Furthermore, implementations SHOULD validate that the
942+
Entity Configuration for the Entity Identifier contains
943+
information compatible with the configured Trust Anchor information
944+
- especially the keys.
945+
This Claim MUST NOT be present in Entity Statements that are not
946+
Explicit Registration responses.
947+
</t>
948+
</list>
949+
</t>
950+
<t>
951+
If any of these validation steps fail,
952+
the Entity Statement MUST be rejected.
953+
</t>
954+
</section>
955+
766956
<section title="Entity Statement Examples" anchor="es_example">
957+
767958
<figure>
768959
<preamble>
769960
The following is a non-normative example of the JWT Claims Set for an Entity Statement.
@@ -876,6 +1067,7 @@
8761067
]]></artwork>
8771068
</figure>
8781069
</section>
1070+
8791071
</section>
8801072

8811073
<section title="Trust Chain" anchor="trust_chain">
@@ -10830,6 +11022,9 @@ Host: op.umu.se
1083011022
<t>
1083111023
Fixed #241: Restructured Entity Statement section.
1083211024
</t>
11025+
<t>
11026+
Fixed #84: Added section on validating Entity Statements.
11027+
</t>
1083311028
</list>
1083411029
</t>
1083511030

0 commit comments

Comments
 (0)