[Openid-specs-ab] Comments on federation draft-08

[Marcos Sanz]

Hi all,

I had a chance to go through the federation draft (though I admit I 
skipped the appendixes because I found them a bit difficult to read) and 
have a couple of comments to make. I have separated comments in category 
"discussion-prone" and simple nits:

Main things:

- Section 5: The usage of well-known URIs is different to what I have seen 
in other OpenID specs: Usually, at the well-known URI you'll find a 
(static) document that will inform you about configuration parameters, 
discovery information, URIs of actual endpoints of the service, and so on. 
However, the federation spec is running the federation API directly under 
"/.well-known/openid-federation". This is, for starters, a break with the 
existing practice in the spec family. I then tried to look for standards 
advice on the topic. In the (now obsolete) RFC 5785 there was the 
following guidance text:

"well-known URIs are not intended for general information retrieval or 
establishment of large URI namespaces on the Web.  Rather, they are 
designed to facilitate discovery of information on a site when it isn't 
practical to use other mechanisms". Also from 5785: "the well-known URI 
space was created with the expectation that it will be used to make 
site-wide policy information and other metadata available directly (if 
sufficiently concise), or provide references to other URIs that provide 
such metadata".

Both sentences have admittedly disappeared in the younger RFC 8615, but 
you'll still find text in 8615 speaking of "metadata discovered by 
dereferencing the well-known URI", which somehow implies what the 
expectations are when you visit that URI, namely, metadata.
Now you could claim that fetching entity statements and doing trust 
negotation is acquiring metadata from the federation, but I think that's 
executing business logic of the API ("Application _Programmers_ 
Interface", see? ;-). On top, I see operational problems in front of us if 
the spec sticks to this well-known URI usage: if it's already difficult to 
place a static document for a service like IdP discovery under 
.well-known/webfinger in the generic domain amazon.com (I heard that from 
an authoritative source at the IIW last year), go figure if you want to 
run application code there.

All in all, I defend using the well-known URI of the federation to 
discover a document where the actual Federation API endpoint is listed. 
(If you all have already discussed about this and then dropped it, then 
I'd be thankful for a pointer in the archives).

- Section 5.4: This looks to me a bit rudimentary. I wonder whether using 
RFC 7807 and the associated media type application/problem+json wouldn't 
be more appropriate to carry problems around. One downside of this, 
though, it's that it hasn't been used so far in the OpenID specs I know 
of: if I used consistency within the spec family as an argument before, I 
should be able to accept some pushback here :-)

- Section 8.1.3: This is underspecified and "fails-to-establish-trust" is 
a place where many things can go wrong. I think the spec should take the 
effort of defining a base set of error codes, the same way for instance 
that the core spec does in section 3.1.2.6. Further, using a catch-all 
"invalid_request" code, which originally was thought as for indicating "
The request is missing a required parameter, includes an invalid parameter 
value, includes a parameter more than once, or is otherwise malformed" 
(RFC 6749), is a misuse.

Nits
- Section 1.2: Definition of "Trust Chain" uses the expression "trusted 
chain", which is self-referential
- Section 4: s/polices/policies/
- Section 4.5: s/parties that wants/parties that want/
- Section 4.6: Last example, there's a spurious comma after the last JSON 
element
- Section 5: s/multi-teanant/multi-tenant/ in all URIs
- Section 5: s/requests to the federation API does/requests to the 
federation API do/
- Section 5.1.2: the example is kind of useless. I am aware that it must 
be a JOSE and all of that, but it's also truncated, so it can't even be 
decoded. I'd rather have an already decoded positive response to show how 
it should look like (plus a caveat that it will never look like that on 
the wire)
- Section 5.2.1: the example uses the parameter "op" while the actual name 
is "operation"
- Section 5.2.2: s/polices/policies/
- Section 5.3.1: the example uses the parameter "op" while the actual name 
is "operation". Also, the example uses a parameter "type" which isn't 
defined in the text above.
- Section 6: The sentence that ends with "...and a list of entity IDs of 
trusted trust anchors together with the public version of their signing 
keys". If I get this right the part "together with the public version of 
their signing keys" is not needed, since federation makes heavy use of 
discovery and, strictly speaking, that public key information will be 
dynamically be read from the trust anchors' jwks_uri, right?
- Section 6.2: Also strictly speaking, the last sentence "no information 
in the chain of statements should be used before the signature chain has 
been validated" directly contradicts with the previous paragraph "an 
implementer MAY therefor chose [sic] to not verify the signature until all 
the other checks have been done".
- Section 7.2: For the first time appears the term "trust root", and it's 
used a couple of times afterwards. If it's the same as "trust anchor", I'd 
rather consistently stick to the latter.
- Section 8.1.1: s/authorization request example/authentication request 
example/ for the sake of consistency
- Section 8.1.1, example: the parameter "state" is twice in the URI. And I 
personally find the usage of "localhost" in the client_id kind of 
distracting.
- Section 11.1: Replace RFC 5785 with 8615

Best regards,
Marcos

-- 
Dipl.-Ing. Marcos Sanz Grossón
Leiter Software Engineering

DENIC eG, Kaiserstraße 75 – 77, 60329 Frankfurt am Main, GERMANY
E-Mail: sanz at denic.de, Fon: +49 69 27235-0, Fax: -235
https://www.denic.de

Angaben nach §25a Absatz 1 GenG: DENIC eG (Sitz: Frankfurt am Main)
Vorstand: Martin Küchenthal, Andreas Musielak, Sebastian Röthler, Dr. Jörg 
Schweiger
Vorsitzender des Aufsichtsrats: Thomas Keller
Eingetragen unter Nr. 770 im Genossenschaftsregister, Amtsgericht 
Frankfurt am Main