Finetune OpenID Connect scope documentation

[soxofaan]

https://openeo.org/documentation/1.0/developers/api/reference.html#operation/authenticate-oidc

under /credientials/oidc, the scopes fields:

scopes (required)   A list of OpenID Scopes that the client MUST use.
                    If empty, the default scopes of OpenID Connect MUST be used.

This is bit confusing: it is required on one hand, but can be empty (in which case default scopes must be used)

I'm also not sure what default scopes mean in this context, but as far as I know, only openid is a required scope to enable OpenID Connect. I would just simplify the doc to state that.

[soxofaan]

I pushed another related commit:

• endpoint doc uses name, while field is actually id
• a description ... optionally added: that's bit redundant given the field listing below that

feel free to finetune further

[m-mohr]

I agree with most of this, thanks.

I'm not sure about the scopes. I think the piece to fix here is the scopes requirement as the description also doesn't list the scopes: "For each OpenID provider, a name and the issuer location MUST be listed." It doesn't say scopes is required and the scopes description basically allows it being empty. Thus some suggestions below.

Please also add a CHANGELOG entry referring to this PR.

[soxofaan]

already pushed some updates (all to be squashed before merging)

some more notes

I think the piece to fix here is the scopes requirement as the description also doesn't list the scopes: "For each ...

Indeed, currently id, issuer, scopes and title are required, but the (endpoint) description only mentions name/id and issuer as "MUST be listed". I considered fixing this incomplete situation by moving stuff from the endpoint description to the field descriptions, but didn't want to move too much at once. It would make things cleaner and more concise however. What do you think?

If no scope is specified, clients MUST use the OpenID Connect default scope openid.

This allows a backend to specify a non-empty list without openid, which breaks OpenID Connect. I would specify something like "if scopes are specified, the list MUST at least contain the openid scope".

[m-mohr]

Suggested change

	For each OpenID provider, an id and the issuer location MUST be listed.
	For each OpenID provider, the issuer location with an id and a title MUST be listed.

[m-mohr]

already pushed some updates (all to be squashed before merging)

Thanks.

Indeed, currently id, issuer, scopes and title are required, but the (endpoint) description only mentions name/id and issuer as "MUST be listed".

I now realized that name was referring to title. So to be very explicit, we should list id, title and issuer.

I considered fixing this incomplete situation by moving stuff from the endpoint description to the field descriptions, but didn't want to move too much at once. It would make things cleaner and more concise however. What do you think?

What exactly? The first paragraphs are just an overview and I think the information in there is already part of the fields, isn't it?

This allows a backend to specify a non-empty list without openid, which breaks OpenID Connect. I would specify something like "if scopes are specified, the list MUST at least contain the openid scope".

Oh yes, add that, please. I just checked whether we can also enforce this with the schema, but OpenAPI unfortunately doesn't allow that. JSON Schema has the contains keyword, but it's not part of OpenAPI yet. We could add x-contains as reminder for later (JSON Schema is on its way) though: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#specificationExtensions

that would be

x-contains:
  const: "openid"

[soxofaan]

What exactly? The first paragraphs are just an overview and I think the information in there is already part of the fields, isn't it?

I just mean that it looks redundant and prone to inconsistencies to have the same information:

• textually in the endpoint description ("for each ... MUST be listed .... [other] ... OPTIONALLY added")
• structurally in the field metadata ("required" vs "not required")

I would propose to move the whole paragraph of the "issuer location" that's currently in the endpoint description to the description of the issuer field. And drop the textual specification of MUST/OPTIONAL fields.

But, I don't feel very strong about this, it's just a minor suggestion to streamline things a bit

[m-mohr]

Yes, that works for me. Merge it, please. :-)

[soxofaan]

Oh yes, add that, please.

It's still like in my original PR, so I'll leave it like that.

enforce this with the schema, but OpenAPI unfortunately doesn't allow that.

One could argue that it's not that big of an issue because leaving out openid scope would be a violation of the OIDC spec, not necessarily openeo spec. I don't think it's the responsibility of openeo API to enforce a whole other spec.

[m-mohr]

It's still like in my original PR, so I'll leave it like that.

I think your proposed "If scopes are specified, the list MUST at least contain the openid scope." is a bit clearer than just "The list MUST at least contain the openid scope.". With that it's ready to be merged, I think.

One could argue that it's not that big of an issue because leaving out openid scope would be a violation of the OIDC spec, not necessarily openeo spec. I don't think it's the responsibility of openeo API to enforce a whole other spec.

I think if we have a requirement in text, we should try to enforce them as much as possible in the schemas. Otherwise we could also just leave it out of the text as well and just refer to OpenID Connect. But I'm not strongly feeling about this workaround.

[soxofaan]

ok, squashed everything and force-pushed

[m-mohr]

Thank you!