1. OpenID Foundation Avatar OpenID Foundation
  2. WGs
  3. connect
  4. Issues

[Federation] Metadata in EC and in ES

Issue #2062 resolved
Michael Fraser created an issue

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 a metadata claim appears beside a metadata_policy claim in an Entity Statement, then for each Entity Type, claims that appear in metadata MUST NOT appear in metadata_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)

  1. Giuseppe De Marco

    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 the metadata claim is optional for Trust Anchors and Intermediates within their issued Entity Statements

    Same 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.

    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

    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?

  3. Michael Jones
    • 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.

  4. Michael Jones

    We talked about this on the 22-Sep-23 Federation Editors' call. Michael Fraser, does Giuseppe’s answer resolve the issue for you?

  5. Michael Fraser 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?

  6. Giuseppe De Marco

    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

  11. Giuseppe De Marco

    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.

    ‌

    ‌

  12. Michael Jones

    You mean to add a federation_entity value with organization_name and logo_uri entries, @Giuseppe De Marco ?

  13. 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

  15. Michael Jones

    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?

  16. Sascha Block

    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

    1. the version parameter must contain the current version of the interface (corresponds to
      info.version of the interface definition DirectoryAdministration.yaml)
    2. the parameter title must contain the title of the interface (equivalent to info.title of the
      interface definition DirectoryAdministration.yaml
    3. the description parameter contains a short description of the interface, the
      product version and a link to the active YAML file.

    …

  19. Giuseppe De Marco

    Checked

    All the examples listed above are coherent with the use of metadata and metadata_policy defined in the specs.

    ‌

  22. Log in to comment
Assignee
Type
bug
Priority
minor
Status
resolved
Component
Federation
Milestone
–
Version
–
Votes
0
Watchers
4
Jira: the preferred issue tracker for Bitbucket. Join the team!