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 the resource and rel 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 and rel 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 the resource and optionally one or more rel parameters to obtain the location of the requested service. If the RP does include any number of rel parameters, one MUST have a value of http://openid.net/specs/connect/1.0/issuer.

Comments (5)