Draft: draft-ietf-gnap-core-protocol

Commentary: Adds a diagram and discussion of protocol state . 
 To edit notification comments on pull requests , go to your . _ 
 The text ( but probably not the diagram ) should mention that each state can also transition into Finalized if a timeout occurs , e.g. if the client is expected to send a continuation request but does n't do so . 
 I think the current state text does mention the timeout in each state , but I did go back and add some more explicit explanation to that was lacking . 
 The description evolving around the state diagram is very clear and helpful , partly because it 's focused on the AS as a semi - autonomous or policy - driven delegate . However , we should acknowledge that the End User , RO and Client as well as the AS are delegates themselves and have distinct privacy interests . For example : Is the RS a delegate of the RO ? Probably . Is the AS a delegate of the RS ? Maybe . Is the  a delegate of the End User ? Almost by definition , yes . Is the End User separately represented by both a Client and a secure  ? Ideally . Because , GNAP tries to steer the RO and other End Users through the same AS we risk confusing or conflating the privacy interests of the various actors . For example : As a RO , I want to minimize the request data an AS can see by having requests go to a delegate that I choose . How do I do that ? As an End User , I want to minimize the request data shared with the AS by having the opportunity to delegate and attenuate the authorization I receive from the AS . As a system architect , I want to have non - repudiate attribution to any and all End Users even when the Client acting on behalf of an End User is a cloud server separate from their hardware - secure mobile authenticator . As an RO , I want to choose my RS separately from my AS as , for example in UK Open Banking . I respect that much of this can be dismissed as out - of - scope for GNAP , but “ delegated access ” begs the question of what is the delegate of the End User as a party with overarching privacy and security interests . 
 GNAP deals with delegation to the client instance . This right is delegated by the RO . The end user uses the client instance to exercise this delegated access . In my view , all other forms of handling delegation explicitly are out of scope for GNAP , but GNAP can accommodate them . 
 When looking at your PR , i get to the same conclusion as ( see details in the related comments ) 
 For clarity , please , the client that is referring to is the client as delegate of the RO . When the end user is using a different client , that client is not a delegate of the RO , depending on how we define “ delegate ” . It would be helpful if the editors could answer the scenario of this issue more directly if possible . 
 I do n't think we have an ambiguity here . " GNAP tries to steer the RO and other End Users through the same AS " : no , this use case is briefly mentioned in section 4 but is not covered by the core spec as such . 
 In we have : If the AS is not chosen by the RO , then asking the RO to share policy is both a privacy ( data minimization ) and a human rights ( forced association ) issue . This issue is core to the platform dominance we have today as document repositories ( as RS ) also bundle managing authorization policy ( as AS ) . 
 There 's nothing in the quote that says that the RO is n't able to chose its AS or that it is required to share a policy . Even if it 's obviously preferable to have the RO exercice its full agency , I believe it really depends on the situation though . For instance the project I currently work for is a national health system , it 's centralised and so the RO does n't have much choice ( well , the only choice is to use or not the plateform ) . Plus I would note that in principle , people today are able to chose whichever service ( google , microsoft , facebook , etc . ) they wish to use . No one forces them to do that . And yet here we are . So this seems like a very subtle issue to me , and not one that any protocol can fix easily . That said , GNAP tries to take as much care as it seems possible to do . I still believe this would be better suited for the  draft , though . 
 This issue and the are both about how much GNAP can or should do normatively . It 's pretty clear that without a normative component , platform centralization will continue and regulators will continue to be captured for lack of appropriate technical options . Whether the issue is dealt with in core or the  draft seems less important than that it be normative for anything labeled GNAP as a delegated authorization protocol . Because this is a subtle issue , I suggest we reach out to the IRTF for their input . Do we know how to do that ? 
 I suggest we transfer this issue to the RS draft , I 'll propose a PR based on your input . Then we can try to get feedback from interested parties , such as HRPC . Would that be fine ? 
 Yes . That should work . 
 Moving this issue to RS 
 explains how an existing request can be modified by a PATCH request to the continuation endpoint . My question is , what happens if such a PATCH request is sent while the interaction for the associated grant request is not yet finished ? I feel like this should not be allowed , but could not find any information anywhere in Section 5 that this is actually forbidden . Section 5.3 also says that the PATCH request may include post - interaction responses . I assume this means that by specifying an interaction reference in the PATCH request the interaction can be finished by the PATCH request , so the question would be what happens if the interaction is not finished and the PATCH request does not contain an interaction reference ? 
 In Section 3.3.4 it says If the PATCH request is considered a continuation request ( which is reasonable since it is sent to the continuation URI ) , this would prohibit a PATCH request before the interaction finishes . However , if no interaction finish mode is used , this does not apply . 
 I believe the cases are covered ( a PATCH ca n't be done when it is pending ) , even if we could make things clearer probably : using PATCH instead of POST aims to provide better signal / control of when the partial update can be made as part of a continuation request ( and it needs to use the continue access token ) when the client ca n't receive a finish method ( redirect or push ) , then it will need to poll regularly ( cf 5.2 ) 
 Summary from editor 's discussion : The grant process is stateful , a grant goes from ( requested ) -(pending approval ) -(approved ) , at least . The PATCH request only makes sense to an ( approved ) grant , the post - interaction requests only make sense for the ( pending ) grant . We can call out this stateful nature and constrain different requests and inputs to specific states . 
 Proposed solution to make a state diagram and add state description in the overall protocol discussion . 
 Modifying an Existing Request :  's note : It seems a little odd to include this in a request but I ca n't see a reason to not allow it . 
 If it seems odd and there is n't a clear use for it , then I think we should simplify things by not having it . 
 Should close ? 
 Should be 
 Modifying an Existing Request :  's note : We do not want the client to be able to get swapped out from underneath the user , especially post - consent . However , including this field in a PATCH update request might be the place to define key rotation for the grant request itself , but we 'd need to be very careful of how that works . And it feels like it might have consequences outside of the request , such as rotating the key for all ongoing grants for a given client instance , which is n't really desirable here . We need a lot more discussion and engineering on this before including it . 
 We could include a warning , saying that the AS should check that it is indeed the same user , typically through validating the sub_id 
 Considering the risks described above . Would n't it seem better to define that as out of scope and expect some dedicated client management API for this use case ? As described in 
 Should be and client management deferred to 
 Modifying an Existing Request :  's note : This would allow the client to do things like gather the user 's identifiers post - request , or gather an assertion from an on - device element that the AS can verify . It opens up potential avenues for trouble if the user here is different from the RO that 's already showed up at the AS or race conditions if the RQ 's identity changes mid - stream . But that said , this seems important for multi - log - in cases and the like , probably . 
 We could include a warning , saying that the AS should check that it is indeed the same user , typically through validating the sub_id 
 Please make it normative . 
 Modifying an Existing Request :  's note : We could state something like " resources and subject MUST NOT be the same as in the initial or previous request " to enforce that this really is a change , but is there value in calling that out here ? Somehow we do probably want to tell the AS to not let a client simply post the same request here to rotate access tokens now that we 've got an explicit function for that , right ? 
 I do n't think it 's a meaningful distinction to make from the client 's perspective ; suggest adding additional text about differentiating between grant PATCH and access token rotation ( new token vs. rotated token ) and close in favor of 
 I think we can close this 
 Continuing During Pending Interaction : Editor 's note : Do we want to be more precise about what 's expected inside the " continue " object ? I think that at least the URI is required , access token required IF used , etc . This is even if they have n't changed since last time , and the client will use whatever value comes back ? 
 Yes , we should be explicit about what 's in here every time , and that it should always be included ( so a client can rely on it always being there and always using the newest value ) . No good argument to optimize by omission , since that leads to lazy clients not checking the return values . One quirk : access token value ; some servers never see the access token 's value after they issue it ( they store the hash or other derived reference ) , and so returning the same value if they want to re - use it is a pain . However , these servers can always rotate the continuation access token , which is recommended ( ) so this point might be moot .
Paragraph (version B):
GNAP is fundamentally designed to allow delegated access to APIs and
other information, such as subject information, using a multi-stage,
stateful process.  This process allows different parties to provide
information into the system to alter and augment the state of the
delegated access and its artifacts.
Paragraph (version B):
While it is possible to deploy an AS in a stateless environment, such
deployments will need a way to manage the current state of the grant
request in a secure and deterministic fashion.
Paragraph (version A):
The request and response MUST be sent as a JSON object in the body of
the HTTP POST request with Content-Type "application/json", unless
otherwise specified by the signature mechanism.
Paragraph (version B):
state).
Paragraph (version B):
The request MUST be sent as a JSON object in the body of the HTTP
POST request with Content-Type "application/json", unless otherwise
specified by the signature mechanism.
Paragraph (version B):
state, as the field contains the information needed by the client
request to continue the request as described in continue-request.
Note that the continuation access token is bound to the client
instance's key, and therefore the client instance MUST sign all
continuation requests with its key as described in binding-keys and
MUST present the continuation access token in its continuation
request.
Paragraph (version B):
state to return this field in the response.
Paragraph (version B):
state, the AS determines what authorizations and consents are
required to fulfill this requested delegation.  The details of how
the AS makes this determination are out of scope for this document.
However, there are several common patterns defined and supported by
GNAP for fulfilling these requirements, including information sent by
the client instance, information gathered through the interaction
process, and information supplied by external parties.  An individual
AS can define its own policies and processes for deciding when and
how to gather the necessary authorizations and consent.
Paragraph (version A):
The AS will verify this presented information in the context of the
client instance's request and can only trust the information as much
as it trusts the presentation and context of the information.  If the
AS determines that the information presented in the initial request
is sufficient for granting the requested access, the AS MAY return
the positive results response with access tokens and subject
information.
Paragraph (version B):
state and return results response with access tokens and subject
information.
Paragraph (version B):
state, the client instance can repeat the interaction process by
sending a continue-modify with new request-interact methods.
Paragraph (version B):
state, the interaction start methods sent by the client instance can
be used to facilitate interaction with the end user.  To initiate an
interaction start method indicated by the response-interact from the
AS, the client instance follows the steps defined by that interaction
method.  The actions of the client instance required for the
interaction start modes defined in this specification are described
in the following sections.
Paragraph (version B):
state.  This is often part of facilitating authorization, but it
could also be used to allow the AS and client instance to continue
negotiating the parameters of the request through modification of the
request.
Paragraph (version B):
state, the response MAY contain any newly-created response-token or
newly-released response-subject.  The response MAY contain a new
response-continue as described above.  If a "continue" field is
included, it SHOULD include a "wait" field to facilitate a reasonable
polling rate by the client instance.  The response SHOULD NOT contain
response-interact.
Paragraph (version B):
state and re-evaluate the authorization in the new context created by
the update request.
Paragraph (version B):
The client instance MAY include the "interact" field as described in
request-interact.  Inclusion of this field indicates that the client
instance is capable of driving interaction with the end user, and
this field replaces any values from a previous request.  The AS MAY
respond to any of the interaction responses as described in response-
interact, just like it would to a new request.
Paragraph (version B):
state, the client instance makes an HTTP DELETE request to the
continuation URI.
Paragraph (version B):
state, it MUST NOT be moved to any other state.