[Federation] Metadata in EC and in ES
Inside section 3.1: https://openid.bitbucket.io/connect/openid-connect-federation-1_0.html#section-3.1 metadata is described as the following
metadata
REQUIRED. JSON object that (…) If the Entity Statement is an Entity Configuration, then the Entity Statement SHOULD contain a
metadata
claim. (…) If ametadata
claim appears beside ametadata_policy
claim in an Entity Statement, then for each Entity Type, claims that appear inmetadata
MUST NOT appear inmetadata_policy
Specifically, the REQUIRED for non-entity configuration Entity Statements
Whereas the examples provided in section A.2.5 https://openid.bitbucket.io/connect/openid-connect-federation-1_0.html#appendix-A.2.5 and A.2.7 https://openid.bitbucket.io/connect/openid-connect-federation-1_0.html#appendix-A.2.7 do not contain a metadata key.
I understand this may be the end result if the metadata key is an empty object given some serializers may choose to omit empty keys, however, I believe the examples should explicitly include this for clarity
Comments (21)
-
-
- changed status to new
-
- changed status to open
We briefly discussed this on the 18-Sep-23 working group call. As Guiseppe suggests, adding an example is one possibility.
-
We talked about this on the 22-Sep-23 Federation Editors' call. Michael Fraser, does Giuseppe’s answer resolve the issue for you?
-
reporter Thanks, Guiseppe and Michael
Yes, I think that does answer it
With the above information, as an implementor, I wonder if clarifying and consolidating the metadata definition and restrictions would help. Namely on the inclusion of the metadata claim not actually being mandatory for trust anchors & intermediates, I wonder then if the REQUIRED notation on the definition of the metadata claim is the best fit? Reading through draft 29 I can see the following guidance on when to include the metadata claim:
3.1 - implying that metadata is by default a required field unless an entity configuration
metadata
REQUIRED. JSON object that…
… If the Entity Statement is an Entity Configuration, then the Entity Statement SHOULD contain a
metadata
claim…6.2 - required (at least federation_entity metadata) when an entity configuration for a trust anchor or intermediate
If the Entity is an Intermediate Entity or a Trust Anchor, the response MUST contain metadata for a federation Entity
This consolidates as; metadata is a required parameter for entity statements unless an entity configuration. If an entity configuration, it is mandatory (for federation_entity metadata type) when the subject is an intermediate entity or trust anchor.
When including Giuseppe’s answer (which makes complete sense) this is extended to not be a required field for entity statements where the leaf configuration in turn did not include a metadata value.
Given these cases would a SHOULD or MAY definition be a better fit?
-
I think that there was a PR where it was moved to OPTIONAL or CONDITIONAL, however that PR has mixed too much stuffs together and we have decided to revert that commit with the will to have it in another PR and then that PR was rejected for other reasons and it seems that this impactful change remained orphan.
If the other editors agrees I’d confirm this as an Issue and I’m going to open a PR to move that attribute to OPTIONAL.
Here the PR, @Michael Fraser feel free to join in the discussion within the PR
https://bitbucket.org/openid/connect/pull-requests/629 -
-
assigned issue to
-
assigned issue to
-
- changed title to [Federation] Metadata in EC and in ES
-
reporter Brilliant - thanks Giuseppe!
-
Should the example at the end of https://openid.net/specs/openid-connect-federation-1_0-29.html#section-3.1 contain a
metadata
claim with afederation_entity
value, and if so, with what endpoints?I completely agree that our examples should be realistic ones because developers will copy them.
We should also be clear what kind of entity that this is an example of.
-
I would put in it
organization_name
logo_uri
Even if I assume that these information should be at the will of the subordinate, It should be able to change these anytime. It’s a choice.
-
You mean to add a
federation_entity
value withorganization_name
andlogo_uri
entries, @Giuseppe De Marco ? -
Yes, I think it’s fair that an accreditation body required that both the org name and its logo remains the same at the time of the entity accreditation, even if It Is just a non normative example
-
Cool - I’ll create a PR to get this going.
-
Wait - I was wrong. That example already has this “metadata” claim, so there’s nothing that we need to do:
"metadata": { "openid_provider": { "issuer": "https://ntnu.no", "organization_name": "NTNU", }, "oauth_client": { "organization_name": "NTNU" } },
Am I missing something?
-
Maybe the following relevant use case could be helpful and relevant in this content?
Within the german telematic infrastrucure there are definitions according metadata via the specification directory service of the national agency for digital medicine | gematik. The Spec can be found here https://fachportal.gematik.de/fachportal-import/files/gemSpec_VZD_V1.15.0.pdf
4.6.1.1 I_Directory_Administration - Reading the metadata
Via operation getInfo the metadata of the interface
I_Directory_Administration can be read.4.6.1.1 GET
This operation returns the metadata of the I_Directory_Administration interface.
A_21786 - VZD, I_Directory_Administration, getInfo
The VZD SHALL implement operation "getInfo" according to table Tab_VZD "I_Directory_AdministrationInfo".Description Returns the metadata (including from the InfoObject) of this
OpenAPI specification.
Input data REST request GET /
operationId: (see DirectoryAdministration.yaml)
Parameter Description
none -
Components User of the interface
Output data REST response with metadata (InfoObject).
Process Flow The VZD returns the metadata of the interface in the
InfoObject data structure.
Error cases The protocol-specific error messages are used
(TCP, HTTP, TLS) and supplemented in DirectoryAdministration.yaml with
specific error descriptions.
[<=]
A_21789-01 - VZD, Implementation I_Directory_Administration (REST).
The VZD SHALL implement the operation according to the following specifications:
The return values MUST contain the currently valid meta information for interface
I_Directory_Administration must be returned. In particular- the version parameter must contain the current version of the interface (corresponds to
info.version of the interface definition DirectoryAdministration.yaml) - the parameter title must contain the title of the interface (equivalent to info.title of the
interface definition DirectoryAdministration.yaml - the description parameter contains a short description of the interface, the
product version and a link to the active YAML file.
…
- the version parameter must contain the current version of the interface (corresponds to
-
Looking at this again this morning, I realized that the originally cited examples at https://openid.net/specs/openid-connect-federation-1_0-29.html#appendix-A.2.5 and https://openid.net/specs/openid-connect-federation-1_0-29.html#appendix-A.2.7 don’t contain
metadata
fields. I’ll create a PR to deal with that. -
Partially addressed by https://bitbucket.org/openid/connect/pull-requests/631. We still need to review the examples to make sure they contain the required
metadata
claims and values. -
Checked
- https://openid.net/specs/openid-federation-1_0-30.html#section-4.1-2.4.6
- https://openid.net/specs/openid-federation-1_0-30.html#section-3.1-11
- https://openid.net/specs/openid-federation-1_0-30.html#section-4.3-5
- https://openid.net/specs/openid-federation-1_0-30.html#section-6.2-3
- https://openid.net/specs/openid-federation-1_0-30.html#section-7.1.2-2
- https://openid.net/specs/openid-federation-1_0-30.html#section-7.2.2-8
- https://openid.net/specs/openid-federation-1_0-30.html#appendix-A.2.1-2
- https://openid.net/specs/openid-federation-1_0-30.html#appendix-A.2.2-4
- https://openid.net/specs/openid-federation-1_0-30.html#appendix-A.2.3-4
- https://openid.net/specs/openid-federation-1_0-30.html#appendix-A.2.3-4
- https://openid.net/specs/openid-federation-1_0-30.html#appendix-A.2.5-4
- https://openid.net/specs/openid-federation-1_0-30.html#appendix-A.2.6-5
- https://openid.net/specs/openid-federation-1_0-30.html#appendix-A.2.7-4
All the examples listed above are coherent with the use of metadata and metadata_policy defined in the specs.
-
This PR aims to resolve this issue
https://bitbucket.org/openid/connect/pull-requests/642 -
- changed status to resolved
- Log in to comment
The example “A.2.5. Entity Statement Published by ‘https://swamid.se' about ‘https://umu.se'“ is an Entity Statement where are present the Federation Entity Keys (top level jwks) and the
metadata_policy
without any protocol specific metadata, since the publication of themetadata
claim is optional for Trust Anchors and Intermediates within their issued Entity StatementsSame for “A.2.7. Entity Statement Published by ‘https://edugain.geant.org' about 'https://swamid.se'“
the metadata should be published within the descendant’s Entity Configuration and may be published by superior’s Entity Statements when these are related for the descendant.
Federation can be used even without any specific specific metadata, then a leaf may publish its entity configuration without any metadata type (considering an empty JSON Object as the current specs allows), then the entity statement would not publish any metadata. This is a special use case, since in the most cases the Leaf will publish at least a protocol specific metadata.
For those examples there are no reasons to force their issuer to include a metadata for the descendants.
Probably you would like to suggest to include in the specs a non-normative example where a superior publishes the metadata related to the descendant?