[Federation] Restructuring the Components section

[Giuseppe De Marco]

Trust Marks (https://openid.net/specs/openid-federation-1_0.html#name-trust-marks) should be moved in the Components (https://openid.net/specs/openid-federation-1_0.html#section-3) section for the following reasons:

• it represents a basic component for the infrastructures of trust
• it doesn’t strictly represent something related to policies alone, its value is more general and wider than the way we define and apply the federation policies

Another restructuring proposal pertains the need to distinguish better than the current text the differences between the entity configurations and the entity statements. The Components section would have a general sub section called “Statements” with the following hierarchical structure:

• Differencies between Entity Configuratio and Entity Statements and common Entries for these
• Entity Configuration and Entries for All Entity Configurations
• Entries for Trust Anchor Entity Configurations
• Entries for Leaf Entity Configurations
• Entries for Intermediate Entity Configurations
• Entity Statement and Entries for All Entity Statements

‌

[Michael Jones]

Entity Statements needs to become a top-level section, as does Trust Chains. We’ll drop the Components top-level section. Trust Marks can also be a top-level section. I think it’s kind of in the right place now, but once we promote it to the top level, we can think in detail about the best section ordering.

The subsections for the Entity Statements section could be:

• Entries for All Entity Statements
• Entries for All Entity Configurations
• Entries for Leaf Entity Configurations
• Entries for Intermediate Entity Configurations
• Entries for Trust Root Entity Configurations
• Entries for Entity Statements that are Not Entity Configurations

Or they could be:

• Entries for All Entity Statements
• Entries for All Entity Configurations
• Entries for Leaf Entity Configurations
• Entries for Intermediate Entity Configurations
• Entries for Trust Root Entity Configurations
• Entries for Non-Entity Configuration Intermediate Entity Statements
• Entries for Non-Entity Configuration Trust Root Entity Statements

Finally, another possible categorization I’d come up with earlier (that I think I don’t like as much is):

• Entries Required in All Entity Statements
• Entries Required in All Entity Configurations
• Entries Required in Leaf Entity Configurations
• Entries Required in Intermediate Entity Configurations
• Entries Required in Trust Root Entity Configurations
• Entries Required in Entity Statements that are Not Entity Configurations
• Entries Optional in All Entity Statements
• Entries Optional in All Entity Configurations
• Entries Optional in Leaf Entity Configurations
• Entries Optional in Intermediate Entity Configurations
• Entries Optional in Trust Root Entity Configurations
• Entries Optional in Entity Statements that are Not Entity Configurations

I would suggest starting with the most general category - Entries for all Entity Statements. That would include "iss", "sub", "iat", "exp", and "jwks".

I don't think we'll know that we have it right until we see how the entries we've defined fit into the categories we choose in practice.

[Giuseppe De Marco]

Entity Statements needs to become a top-level section, as does Trust Chains. We’ll drop the Components top-level section. Trust Marks can also be a top-level section

Fully agree.

Regarding the proposal for the section, I’m in favor of this one

• Entries for All Entity Statements
• Entries for All Entity Configurations
• Entries for Leaf Entity Configurations
• Entries for Intermediate Entity Configurations
• Entries for Trust Root Entity Configurations
• Entries for Non-Entity Configuration Intermediate Entity Statements
• Entries for Non-Entity Configuration Trust Root Entity Statements

I suggest to start with the entity configuration, because the federation entity discovery starts with it, from the leaf, and the EC is the first artifact to understand before start.

I didn’t understand the following ones, we’ll discuss them during the next editor call

• Entries for Non-Entity Configuration Intermediate Entity Statements
• Entries for Non-Entity Configuration Trust Root Entity Statements

‌

[Michael Jones]

The last two are about claims that occur in Entity Statements that are not Entity Configurations. These are Entity Statements made by one entity about another one.

[Giuseppe De Marco]

We have the definitions and claims of the entity configuration in the respective sections

We want the distinction of entity configuration from entity statements, and the sections I agreed seems to have everything needed

Details by voice, we’ll get the definite approach together with all the required clarifications

[Michael Jones]

I suggest that we create one or more proposals with just section titles and the claim names that will be described in those sections, to make it easy to visualize the result. I think this is too complicated to try to do by voice.

My personal preference would be to start with the most general claims, “Entries for All Entity Statements”, and proceed from there.

[Giuseppe De Marco]

Entity Statements and Configurations
Introduction of the differences between the entity configuration and the entity statements.
EC: clarifications about sub and jwks, iss==sub and jwks related to iss.
ES: clarifications about sub and jwks, iss!=sub and jwks related to sub.

Entries for All Entity Statements and Entity Configurations

• iss
• sub
• iat
• exp
• jwks
• metadata

Entries for TA Entity Configurations

In addition to the [Entries for All Entity Statements and Entity Configurations]

• constraints (TA only)
• trust_marks_issuers (TA only)
• trust_mark_owners (TA only)

Entries for Leaf and Intermediate Entity Configurations

• authority_hints
• trust_marks

Entries for All Entity Statements

• metadata_policy
• trust_marks (containing the trust marks issued by the statement issuer to the subject, if any)
• constraints
• source_endpoint
• crit
• policy_language_crit

‌

[Michael Jones]

Thanks for doing this. It’s a good starring point. I think you only want “constraints” the second place that it appears. (Or does it belong in a new category for TA & Intermediate Entity Statements?)

This makes it look silly that we have trust_marks_issuers but trust_mark_owners. Why didn’t we call it trust_mark_issuers? That sounds way more natural (at least as English).

[Giuseppe De Marco]

About constraints, I would not add any other section following the common human brain limits about how many stuffs we can keep in mind: it would be 1 the best, but two is often required, but no more than 3 to avoid stress. That’s not a case that in harmony two notes tell you tonic and the dominant (chord), and three notes is the best way to represent it with more detail (if minor or major). Even in OOP I avoid hierarchy superior than 3 levels.

With the proposed approach we have only 2 levels of hierarchy, a common base for all and a specialization by statement-configuration or federation role

[Giuseppe De Marco]

Not answered yet to you Mike.

I may agree that constraint could be moved to the base commons but I would avoid this to keep the base commons without any conditional text.

[Michael Jones]

BTW, please don’t create a PR for this issue until we’ve all agreed on a plan. This will be a major textual upheaval and it will be easier to do it once than to have endless comments on a PR.

[Michael Jones]

https://bitbucket.org/openid/connect/pull-requests/676 (Subordinate Statements) eliminates the Components section title, moving its subsections up to top-level sections. It also makes the Entity Statement claims clearer. After it’s merged, let’s have another look at this.

[Michael Jones]

The Components section no longer exists; its former subsections are now top-level sections.

[Michael Jones]

The top-level sections are now:

1. Introduction
2. Overall Architecture
3. Entity Statement
4. Trust Chain
5. Metadata
6. Federation Policy
7. Obtaining Federation Entity Configuration Information
8. Federation Endpoints
9. Resolving the Trust Chain and Metadata
10. Updating Metadata, Key Rollover, and Revocation
11. OpenID Connect Client Registration
12. Claims Languages and Scripts
13. Security Considerations
14. IANA Considerations

As I see it, 7 (Obtaining Federation Entity Configuration Information) and 9 (Resolving the Trust Chain and Metadata) should be next to one another, followed by 10 (Updating Metadata, Key Rollover, and Revocation). Should we move 8 (Federation Endpoints) to be after 10? Or should 8 go before 7?

‌

[Roland Hedberg]

I think 8 should go before 10. 8 lists what APIs you can access. 7,9 and 10 is about how to use those APIs.

[Michael Jones]

So @Roland Hedberg , you’re proposing that these sections should be in this order, correct?

• Federation Endpoints
• Obtaining Federation Entity Configuration Information
• Resolving the Trust Chain and Metadata
• Updating Metadata, Key Rollover, and Revocation

‌

[Roland Hedberg]

Yes

[Giuseppe De Marco]

I agree.

[Vladimir Dzhuvinov]

+1 for this new order with Roland’s correction

[Michael Jones]

The Federation Endpoints section has been moved before the Obtaining Federation Entity Configuration Information section.