Repository navigation
Conversation
This adds minimal GNAP support using access reference strings to the existing Security Scheme Object and Security Requirement Object. Resource Access Rights (in place of reference strings) are being addressed in a companion specification.
I blame a syntax highlighting bug.
|
|
||
| With RS-first usage, a request to a protected resource results in | ||
| a `401 Unauthorized` response with a `WWW-Authenticate` that at least | ||
| includes the `as\_uri` parameter that provides the grant request endpoint. |
There was a problem hiding this comment.
The following normative text (unless I am mistaken) says that as_uri is optional: https://www.rfc-editor.org/info/rfc9635/#section-9.1-2
The RS MAY additionally return the following OPTIONAL parameters
So there's no guarantee on as_uri being present.
However, based on the RS-first text its not abundantly clear what happens next... I think from the perspective of forming the shape of the response, caveating this proposal that returning as_uri is an expected response, but not specifically protocol bound right now.
Unless you have insight on what happens next here in the case as_uri is not returned I'd say it be worth getting an opinion from Justin Richer on this.
There was a problem hiding this comment.
@SensibleWood If you take a look at the examples, I show configurations where as_uri is missing, where access is missing, and where both are missing.
Of course, you can write an OAD with a security scheme that is inadequate for your API's configuration, but that's true of everything and not something we can fix in the OAS.
There was a problem hiding this comment.
So based on your response, this adds even more weight to ensuring that the following text:
With RS-first usage, a request to a protected resource results in
a401 Unauthorizedresponse with aWWW-Authenticatethat at least
includes theas_uriparameter that provides the grant request endpoint.
Contains the caveat as as_uri is expected when this pattern is used in OpenAPI, which I think is a valid statement to make in the context of the wording above.
There was a problem hiding this comment.
Oh I see what you mean now. Yes, good point, I have updated the text to align with the RFC and added an example response. Please let me know if it still needs work!
| ## Proposed solution | ||
|
|
||
| Minimal GNAP support using access reference strings can be enabled | ||
| by adding a Security Scheme Object `type: gnap` with an optional |
There was a problem hiding this comment.
Do you think this is the opportunity to move away from a one-size-fits-all Security Schema Object and towards a target where different security objects represent different schemes. I think I allude to this approach in the security proposal.
This approach would allow for:
- A separation of concerns between different security protocols
- Avoid bundling everything into the same object, which would
- Avoid an explosion of properties being added into the same Security Scheme Object.
This would be a nice time to introduce such a change, as its the first move away from OpenAPI to towards a dedicated specification.
There was a problem hiding this comment.
I think this does sound solid but in general the goal is to add support for GNAP in some form in the next (soon!) release, and iterate from there. My understanding is that the refactoring suggested here might be a long process and we should try to incrementally hit some released features as milestones along that aspirational journey.
There was a problem hiding this comment.
@lornajane I appreciate the need to iterate, however there is also an opportunity not to iterate on this.
I say this for the following reasons:
- GNAP is new.
- A bunch of folks will implement at v3.3.
- Lets say (for the sake of argument) we go with the proposal to split Security Schemes out into separate objects at v3.4.
- Those same bunch of folks will then need to migrate to revised features at v3.4, one minor release later.
For something brand new like GNAP, that doesn't feel optimal for the community (some of whom will be coming to use OpenAPI specifically for GNAP). It would be nice to set a path we could follow for a few releases.
There was a problem hiding this comment.
@SensibleWood I personally do not have the time available to do a larger refactor. As you may recall from earlier in the year, that was originally the plan. But circumstances have changed and there are no longer resources for that larger effort. I currently do not see any other way to get GNAP out the door for OAS 3.3 / OASS 1.0 with the available resources.
There was a problem hiding this comment.
I'd rather have GNAP available than not. And I don't think we can necessarily deliver perfect AND soon. So really just trying to give some insight into how the meeting discussion went on those points yesterday. I'm not suggesting we publish something half-baked, and we are always conscious of the impact of our upgrade path choices, but we are conscious of the need to do the most we can with the resources we have. A big refactor is essentially unachievable at this time and I felt it was appropriate to say so.
There was a problem hiding this comment.
A big refactor is essentially unachievable at this time and I felt it was appropriate to say so.
@lornajane I am happy with your position. However - and in the same vein - I think it is appropriate to express my thoughts on what I think is the optimal path.
If the TSC is happy with this approach and community members are happy that this may flip from a Security Scheme object to a dedicated object in the future then the path to delivering this is acceptable.
|
|
||
| Minimal GNAP support using access reference strings can be enabled | ||
| by adding a Security Scheme Object `type: gnap` with an optional | ||
| `gnapAsUri` field, and allowing GNAP access strings in the Security |
There was a problem hiding this comment.
does "access strings" mean the resource type values, or the resource handle strings?
There was a problem hiding this comment.
@jricher I'm more than happy to improve the language to reduce confusion. I'm mostly trying to avoid further overloading "reference" which already means several different things in the OAS. I see in this paragraph I call them both "access reference strings" and "access strings", but perhaps being consistent with "access reference strings" would be better?
|
|
||
| Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2’s common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749], OAuth2 device authorization flow as defined in [RFC8628], [OpenID-Connect-Core], and GNAP as defined in [RFC9635]. | ||
|
|
||
| Please note that as of 2020, the implicit flow is about to be deprecated by OAuth 2.0 Security Best Current Practice. Recommended for most use cases is Authorization Code Grant flow with PKCE. |
There was a problem hiding this comment.
The BCP is published: https://www.rfc-editor.org/info/rfc9700/
This adds minimal GNAP support using access reference strings to the existing Security Scheme Object and Security Requirement Object.
Using Resource Access Rights (RAR) in place of reference strings is being addressed in a companion proposal, coming soon.