-
assigned issue to
Alternative wording to avoid confussion around rel param requirment in WebFinger query
In section 2 of OpenID Connect Discovery, it says that:
Issuer discovery requires the following information to make a discovery request … resource … host … rel.
This word "requires" (though not capitalized) has confused some people into thinking that rel
is a REQUIRED parameter in the query. In particular the foundation’s RP test tool made this mistake. I would say that this is relatively clear considering that:
- host isn’t a valid input parameter to a WebFinger query, so it should be apparent that this is a list is about general info the RP needs to have at its disposal depending on the type of query it is making.
- The same section and many others references RFC 7033 which clearly outlines the optionality of
rel
. - The reference in the disco spec to WebFinger is a normative one.
- Other specs, like RFC 8414, OAuth Authorization Serer Metadata, cite section 2 of the OpenID Discovery; that RFC, for instance, says that the client “may be dynamically discovered, for instance, through the use of WebFinger [RFC7033], as described in Section 2 of ‘OpenID Connect Discovery 1.0’,” clearing pointing out that the query follows WebFinger.
Despite all this, there is confusion. I think this misunderstanding is exacerbated by the second sentence in the fourth paragraph of section 2 that says:
Then [the replying party] makes an HTTP
GET
request to the Host's WebFinger [RFC7033] endpoint with theresource
andrel
parameters to obtain the location of the requested service.
I think the confusion can be rectified with two small changes:
- Add a sentence between
host
andrel
in the list like this:
host
Server where a WebFinger service is hosted.
The RP MAY also need the following URI (e.g., if it includes the
rel
parameter to query for multiple link relation types in one request or to reduce the response data from a WebFinger Host that returns extraneous information that the RP is not in need of.)rel
URI identifying the type of service whose location is being requested.
2. Update the previously quoted sentence in the fourth paragraph of section 2 to be this instead:
Then it makes an HTTP
GET
request to the Host's WebFinger [RFC 7033] endpoint with theresource
and optionally one or morerel
parameters to obtain the location of the requested service. If the RP does include any number ofrel
parameters, one MUST have a value ofhttp://openid.net/specs/connect/1.0/issuer
.
Comments (5)
-
-
- changed status to open
-
We could change “requires” to “needs” to avoid confusion.
I agree that we should make it clear that including “rel” parameter is optional, in the way that you suggest.
The referent of “the following URI” in the proposed first addition isn’t clear. What point were you trying to convey with that wording?
-
Will be fixed by https://bitbucket.org/openid/connect/pull-requests/598
-
- changed status to resolved
- Log in to comment