Add a mention of `authorizationRequirements.accessReference` in section 2.4

[peombwa]

The API Manifest spec should add a mention of authorizationRequirements.accessReference in section 2.4 and/or link to its spec.

See discussion at microsoft/OpenApi.ApiManifest#7.

[baywet]

@darrelmiller (or Peter if you have the answers) I started looking at that but I'm not able to "guess" all the aspects of that.
From looking at the implementation code you can either use accesses or accessReferences (should we pluralize those properties since they both contain collections?) but not both at the same time. Is that the intent or simply some implementation drift? (over no spec).

Also could we get an example of the strings in there? it's a reference to what data in the manifest? (seems there doesn't seem to be a place to define access objects outside of the authorization requirements)

[darrelmiller]

Accessreference was an implementation detail. In the original definition of RAR https://datatracker.ietf.org/doc/html/rfc9396#section-2 which was first defined in GNAP https://www.ietf.org/archive/id/draft-ietf-gnap-core-protocol-15.html#section-8.1 the "access" property, which in RAR is called "authorization_details" could either be an array of objects or an array of strings. This is why it is declared as:

? access: [+accessRequest] | [+tstr]

I did not realize that when they wrote RAR they dropped the array of string option. The array of strings is a really nice feature because it is what we currently do in OpenAPI. Having support for both an array of strings and an array of objects gives a lot of flexibility.

[baywet]

@darrelmiller my question was regarding accessReference, not access in that case. Unless we should drop accessReference in favour of access only?

[peombwa]

@darrelmiller, looking at https://www.ietf.org/archive/id/draft-ietf-gnap-core-protocol-15.html#section-8.1, access can include a collection of both object-type and string-type, which can be difficult to model in some strongly typed language due to lack of union types (coughs c#...).

I'm with @baywet on reviewing whether we should drop accessReference in favor of access to align with the current version of RAR.