Draft: draft-ietf-gnap-core-protocol

Commentary: This change set extracts the resource - server - focused elements of GNAP to allow the core protocol to focus on the client - AS relationship while this new document can focus on the RS - AS relationship . remove RS section for refactoring RS section now at : 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-246 - -gnap - core - protocol - editors- 
 Regarding Why this specification ca n't state it even in a more generic way similar to what does ? There are use cases when we may need to exchange an access token and then use it with something completely different than chained RSs . 
 Maybe this is a bit unrelated but ... The self - contained tokens usually contain one or another form of the issuer . What would be the issuer for GNAP ? Is it the grant endpoint ? 
 I 'd be happy to see proposed language to discuss ! The limitation is to keep parity with the " token request " mechanism in the core draft : the goal is to get an access token , but based on the context of an existing access token . One of the problems I 've always had with RFC8693 is that it tries to be many things at once , from access token exchange to assertion exchange to likely other use cases . If other functions should be to this spec then we can do that , but hopefully we wo n't run the same risk of putting everything through the same narrow pipe . Technically since it 's a basic  request , you can already return subject identifiers or assertions as well , but we do n't currently talk about any of that . Should we ? 
 The concept of the " issuer " entirely depends on the type of token . The grant endpoint would be an obvious value for GNAP though , and if we 're going to go down the route of discussing token contents from a structural standpoint ( or even profile things like JWT or Biscuits or PASETO ) then we can make that recommendation . However , the current text is intended to be at a much higher level than that , right now . 
 I also wonder if  is going to support encrypted token introspection responses on its core ? 
 Another thing I would like to understand better if  is going to rely completely on TLS ... or it would its own responses such as token introspect responses say using ( or other means ) a way to cryptographically link a request from the client to AS 's response TLS is n't going anywhere ... It 's a must . Although , in certain forms of envs , it 's great to have an additional layer on top of it . 
 Regarding , However , the current text is intended to be at a much higher level than that , right now . It 's understandable . It 's entirely possible I missed something in the current spec but it would be nice to say that a URL of the grant endpoint also represents something the does in other identity - related specs . I hope it makes some sense . 
 : Section 3.3 ( introspection ) is put here right now because introspection is an API presented to the RS by the AS , just like the others . I 'm very open to reorganizing the whole document though as it does need to be more cohesive . This pull was a first step . This is currently covered in 3.2 , the AS can pre - configure the identifiers or let the RS just present a key at runtime . This discussion needs to be expanded along with security considerations for both practices , and ways to do the binding dynamically ( like return the value at runtime , the way a client instance ID is returned ) 
 Folks , I have a strong preference for the new document to live in its own repo ( see for pros and cons ) . Any objections ? 
 I 'm fine with this being in its own repository or in the same one -- I 've used both in different groups and each has its benefits and drawbacks . If the chairs set up the repo I can import the support code and check in this document in its own PR . 
  document now moved to 
 Resource Servers :  's note : This section is for discussion of possible advanced functionality . It seems like it should be a separate document or set of documents , and it 's not even close to being well - baked . This also adds additional endpoints to the AS , as this is separate from the token request process , and therefore would require RS - facing discovery or configuration information to make it work . Also - also , it does presume the RS can sign requests in the same way that a client does , but hopefully we can be more consistent with this than  was able to do . 
 Section 10 mentions : Calling back the AS , allows the AS to know to the existence of the RS . There are cases where the AS should be prevented to know which the RS is . When doing " Token Introspection " ( Section 10.1 ) , the AS may communicate to the RS some privileges without the client ( and hence the end - user ) knowing it ( and thus without the end - user consent ) . " Deriving a downstream token " ( Section 10.2 ) is described to allow a RS to act as a client instance and request a derived access token for a secondary RS . This can be done without a recall to the AS , if the name of the service to which the first RS belongs to is included into the access token . See the issue which contains more details on how to do it . " Registering a Resource Handle " ( Section 10.3 . ) allows the AS to know which RSs are trusting it . This should be avoided for RSs as soon as there is no bi - lateral trust relationships with the AS . This should also be avoided to allow large scale developments . A RS trusts some ASs to some extent , but the ASs do not necesarilly need to know which RSs are trusting them . Requesting Resources With Insufficient Access ( Section 10.4 ) is addressed in another issue . See " Requesting resources with insufficient access " The whole section would need to be re - written . 
 Section 10 is made of optional elements . Token introspection is not required , you could alternatively use a self - contained token . Deriving a token without the AS 's involvement is deeply problematic for most use cases as the AS is the root of trust in the system and overriding that would subvert the security model . Yes , introducing the RS to the AS lets the AS know about the RS as this is the point . 
 ( Section 10.4 ) Requesting Resources With Insufficient Access is NOT an optional element . Nevertheless , it is addressed in another issue . See " Requesting resources with insufficient access " . At the moment the text states : The phrasing of section 10 should be reworded to indicate that the sub - sections 1 , 2 & 3 describe optional functions . You also wrote : " introducing the RS to the AS lets the AS know about the RS as this is the point " . I do understand that this is necessary for some use cases , but not for all use cases , in particular when ACLs are used by the RS instead of capabilities 
 This section will be pulled out into a separate document , to be discussed by the working group . Note that in the future it could be re - incorporated into the core if the working group decides to restructure things that way . 
 I think that 's a good starting point . A few general remarks : Seems to me that 3.3 is more an AS facing API . We could have a paragraph 3 focused on  APIs ( well known , registering a resource handle , etc . ) , and regroup the other items in a section that discusses how the RS reacts when a client calls it ( i.e. current sections 3.3 , 4 and 5 ) Will we need some kind of resourceserver instance to declare a stable " resourceserver " : " 7C7C4AZ9KHRS6X63AJAO " ? ( beyond tne reference , which seems chosen here by the RS ? )
Paragraph (version B):
The AS determines that interaction is needed and response with a
response-interact-redirect and response-interact-finish in (7).
The AS also includes information the client instance will need to
response-continue in (8).  The AS associates this continuation
information with an ongoing request that will be referenced in
(4), (6), and (8).
Paragraph (version B):
In this scenario, the client instance does not call an RS and does
not request an access token.  Instead, the client instance only
requests and is returned response-subject.  Many different
interaction modes can be used in this scenario, so these are shown
only in the abstract as functions of the AS here.
Paragraph (version B):
The client instance facilitates authorization as directed in (2).
Paragraph (version A):
The AS can determine the RO's identity and permission for releasing
this information through user-interaction, AS policies, or request-
user.  If this is determined positively, the AS MAY response-subject
as requested.
Paragraph (version B):
The AS can determine the RO's identity and permission for releasing
this information through authorization, AS policies, or request-user.
If this is determined positively, the AS MAY response-subject as
requested.
Paragraph (version A):
Many times, the AS will require interaction with the RO in order to
approve a requested delegation to the client instance for both access
to resources and direct subject information.  Many times the end-user
using the client instance is the same person as the RO, and the
client instance can directly drive interaction with the AS by
redirecting the end-user on the same device, or by launching an
application.  Other times, the client instance can provide
information to start the RO's interaction on a secondary device, or
the client instance will wait for the RO to approve the request
asynchronously.  The client instance could also be signaled that
interaction has completed by the AS making callbacks.  To facilitate
all of these modes, the client instance declares the means that it
can interact using the "interact" field.
Paragraph (version B):
The client instance declares the parameters for interaction methods
that it can support using the "interact" field.
Paragraph (version B):
If this interaction mode is supported for this client instance and
request, the AS returns a redirect interaction response response-
interact-redirect.  The client instance manages this interaction
method as described in interaction-redirect.
Paragraph (version A):
In this example, the AS is returning an response-interact-redirect, a
response-interact-callback, and a response-continue.
Paragraph (version B):
In this example, the AS is returning an response-interact-redirect, a
response-interact-finish, and a response-continue.
Paragraph (version B):
The means for the launched application to communicate with the AS are
out of scope for this specification.
Paragraph (version B):
If the client instance indicates that it can request-interact-finish
and the AS supports this mode for the client instance's request, the
AS responds with a "finish" field containing a nonce that the client
instance will use in validating the callback as defined in
interaction-finish.
Paragraph (version A):
The AS MUST create an interaction reference and associate that
reference with the current interaction and the underlying pending
request.  This value MUST be sufficiently random so as not to be
guessable by an attacker.  The interaction reference MUST be one-
time-use.
Paragraph (version A):
The AS then MUST send the hash and interaction reference based on the
interaction finalization mode as described in the following sections.
Paragraph (version B):
The client instance MUST NOT modify the URI when launching it, in
particular the client instance MUST NOT add any parameters to the
URI.  The URI MUST be reachable from the end user's browser, though
the URI MAY be opened on a separate device from the client instance
itself.  The URI MUST be accessible from an HTTP GET request and MUST
be protected by HTTPS or equivalent means.
Paragraph (version B):
The AS MUST create an interaction reference and associate that
reference with the current interaction and the underlying pending
request.  This interaction reference value MUST be sufficiently
random so as not to be guessable by an attacker.  The interaction
reference MUST be one-time-use to prevent interception and replay
attacks.
Paragraph (version B):
The AS MUST calculate a hash value based on the client instance and
AS nonces and the interaction reference, as described in interaction-
hash.  The client instance will use this value to validate the
"finish" call.
Paragraph (version B):
The AS has determined that any URIs involved with the finish
method are dangerous or blocked.
Paragraph (version B):
The AS cannot determine which ongoing grant request is being
referenced.
Paragraph (version B):
The ongoing grant request has been cancelled or otherwise blocked.
Paragraph (version B):
When the AS responds to the client instance's "finish" method as in
interaction-callback, this response includes an interaction
reference.  The client instance MUST include that value as the field
"interact_ref" in a POST request to the continuation URI.
Paragraph (version B):
When the client instance does not include a "finish" parameter, the
client instance will often need to poll the AS until the RO has
authorized the request.  To do so, the client instance makes a POST
request to the continuation URI as in continue-after-interaction, but
does not include a message body.
Paragraph (version B):
When neither an access token nor key proof are used, this is an
unsecured request.  This type of request is not used in the core
protocol of GNAP.
Paragraph (version A):
In some deployments, a resource server will need to be able to call
the AS for a number of functions.
Paragraph (version A):
The AS validates the access token value and the client instance's
request and returns the introspection response for the token.
Paragraph (version A):
The RS signs the request with its own key and sends the access token
as the body of the request.
Paragraph (version A):
The AS responds with a data structure describing the token's current
state and any information the RS would need to validate the token's
presentation, such as its intended proofing mechanism and key
material.
Paragraph (version A):
The AS returns a derived token to RS1 for use at RS2.
Paragraph (version A):
RS1 calls RS2 with the token from (3).
Paragraph (version A):
RS2 fulfills the call from RS1.
Paragraph (version A):
If the RS needs to derive a token from one presented to it, it can
request one from the AS by making a token request as described in
request and presenting the existing access token's value in the
"existing_access_token" field.
Paragraph (version A):
The AS responds with a handle appropriate to represent the resources
list that the RS presented.
Paragraph (version A):
The RS MAY make this handle available as part of a rs-request-
without-token or as documentation to developers.