Draft: draft-ietf-gnap-core-protocol

Commentary: This text clarifies the intent of an object within the request array , and the nature of combining multiple objects . Added examples should help explain the intended usage . please review to see if this addresses the concern you raise in 
 I 'm in favor of having specific examples like this in - line but using an appendix for something more in - depth , like a fully specified request and response , in context with all the messages . 
 Netlify deployed gnap - core - protocol - editors - draft as draft https://--gnap - core - protocol - editors- 
 Currently the value of is a set of strings known to or understandable by the RS , and it 's recommended that URIs be used in this field . Should this instead be defined as URIs ? Do we need a separate field for a non - URI style identifier ? Originally posted by in 
 Possibly , but would need to explicit the use case for non URI first . 
 To keep aligned with RAR ( ) , the value will continue to be a list of strings that MAY be URIs . 
 Should the AS always return the " resources " structure to the RC in the token structure response ? This is currently " RECOMMENDED " with little guidance as to when to return it or not . It seems like it could be made required without placing additional burden on the client . Originally posted by in 
 Will make a REQUIRED field , even if left empty by the AS . 
 Related : the continuation access token uses the same structure but does n't have " access " because it 's a limited use token already . Should we define a " type " for continuation access tokens in GNAP and use it here ? Strawman : type : https://url - of - gnap - RFC/ actions : continue locations : grant    ? It 's always going to be the same , so it might get ignored like " token_type : bearer " is ignored by OAuth clients . 
 Token Management :  's note : Should we allow for " update " to an access token by the client posting new information from a " request " ? It seems this might make things weird since an access token is generally considered an unchanging thing , and the client could always request a new access token if they 're allowed to continue the grant request post - issuance as in Section 5.3 . There 's also a possibility of being able to " read " a token 's state with a GET , much like token introspection but using the token's / client 's key instead of the RS key . But would a client need to " read " a token state after issuance ? Is there a security risk to offering that functionality ? Introspection is nearly always relegated to RS calls in practice since the client is focused on using the token at the RS . The client can always read the state of the grant itself , separately . 
 See also discussion on " read " action at 
 Tokens are meant to be immutable . So update is not in the scope of what we want to do . Read access : we do n't see any compelling reason to allow read access + might be an issue for privacy . Please clarify how the mecanism would work , especially with privacy considerations . Marked as need text . Without additional text , this section will be removed in a future update . 
 Closing the issue following the merge of the PR 
 Yaron : it 's implied but should be spelled out that the semantics of this example is the cross product of permissions : I am requesting to read and write and " dolphin " both " metadata " and " images " , and that applies to both " locations " - 12 different possible actions .  : OK , that can be expounded upon here , as that is the intent . Each object is meant to encompass one fully realized combination of options , which is why they ’re presented in an array overall ( as talked about above ) . Yaron : this is critical to the protocol semantics . 
 LGTM , except for one typo ( separate comment ) .
Paragraph (version A):
Manages the requested delegations for the RO.  The AS issues
tokens and directly delegated information to the RC.  The AS is
defined by its grant endpoint, a single URL that accepts a POST
request with a JSON payload.  The AS could also have other
endpoints, including interaction endpoints and user code
endpoints, and these are introduced to the RC as needed during the
delegation process.
Paragraph (version A):
Requests tokens from the AS and uses tokens at the RS.  An
instance of the RC software is identified by its key, which can be
known to the AS prior to the first request.  The AS determines
which policies apply to a given RC, including what it can request
and on whose behalf.
Paragraph (version A):
Accepts tokens from the RC issued by the AS and serves delegated
resources on behalf of the RO.  There could be multiple RSs
protected by the AS that the RC will call.
Paragraph (version A):
Authorizes the request from the RC to the RS, often interactively
at the AS.
Paragraph (version A):
Operates and interacts with the RC.
Paragraph (version A):
Multiple roles can be fulfilled by the same party, and a given party
can switch roles in different instances of the protocol.  For
example, the RO and RQ in many instances are the same person, where a
user is authorizing the RC to act on their own behalf at the RS.  In
this case, one party fulfills both of the RO and RQ roles, but the
roles themselves are still defined separately from each other to
allow for other use cases where they are fulfilled by different
parties.
Paragraph (version A):
For another example, in some complex scenarios, an RS receiving
requests from one RC can act as an RC for a downstream secondary RS
in order to fulfill the original request.  In this case, one piece of
software is both an RS and an RC from different perspectives, and it
fulfills these roles separately as far as the overall protocol is
concerned.
Paragraph (version A):
A single role need not be deployed as a monolithic service.  For
example, An RC could have components that are installed on the RQ's
device as well as a back-end system that it communicates with.  If
both of these components participate in the delegation protocol, they
are both considered part of the RC.
Paragraph (version A):
For another example, an AS could likewise be built out of many
constituent components in a distributed architecture.  The component
that the RC calls directly could be different from the component that
the the RO interacts with to drive consent, since API calls and user
interaction have different security considerations in many
environments.  Furthermore, the AS could need to collect identity
claims about the RO from one system that deals with user attributes
while generating access tokens at another system that deals with
security rights.  From the perspective of GNAP, all of these are
pieces of the AS and together fulfill the role of the AS as defined
by the protocol.
Paragraph (version A):
A credential representing a set of access rights delegated to the
RC.  The access token is created by the AS, consumed and verified
by the RS, and issued to and carried by the RC.  The contents and
format of the access token are opaque to the RC.
Paragraph (version A):
A cryptographic element binding a request to a holder of the key.
Access tokens and RC instances can be associated with specific
keys.
Paragraph (version A):
A protected API served by the RS and accessed by the RC.  Access
to this resource is delegated by the RO as part of the grant
process.
Paragraph (version A):
Information about the RO that is returned directly to the RC from
the AS without the RC making a separate call to an RS.  Access to
this information is delegated by the RO as part of the grant
process.
Paragraph (version B):
For another example, in some complex scenarios, an RS receiving
requests from one client instance can act as a client instance for a
downstream secondary RS in order to fulfill the original request.  In
this case, one piece of software is both an RS and a client instance
from different perspectives, and it fulfills these roles separately
as far as the overall protocol is concerned.
Paragraph (version A):
Note that a connection between roles in this process does not
necessarily indicate that a specific protocol message is sent across
the wire between the components fulfilling the roles in question, or
that a particular step is required every time.  For example, for an
RC interested in only getting subject information directly, and not
calling an RS, all steps involving the RS below do not apply.
Paragraph (version B):
Note that a connection between roles in this process does not
necessarily indicate that a specific protocol message is sent across
the wire between the components fulfilling the roles in question, or
that a particular step is required every time.  For example, for a
client instance interested in only getting subject information
directly, and not calling an RS, all steps involving the RS below do
not apply.
Paragraph (version A):
In this example flow, the RC is a web application that wants access
to resources on behalf of the current user, who acts as both the
requesting party (RQ) and the resource owner (RO).  Since the RC is
capable of directing the user to an arbitrary URL and receiving
responses from the user's browser, interaction here is handled
through front-channel redirects using the user's browser.  The RC
uses a persistent session with the user to ensure the same user that
is starting the interaction is the user that returns from the
interaction.
Paragraph (version A):
The RC establishes a verifiable session to the user, in the role
of the RQ.
Paragraph (version A):
The RC request.  The RC indicates that it can request-interact-
redirect and request-interact-callback.  The RC stores
verification information for its callback in the session created
in (1).
Paragraph (version A):
The AS determines that interaction is needed and response with a
response-interact-redirect and response-interact-callback in (7).
The AS also includes information the RC 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 A):
The RC stores the verification and continuation information from
(3) in the session from (1).  The RC then interaction-redirect
given by the AS in (3).  The user's browser loads the interaction
redirect URL.  The AS loads the pending request based on the
incoming URL generated in (3).
Paragraph (version A):
When the AS is done interacting with the user, the AS interaction-
callback to the RC using the callback URL provided in (2).  The
callback URL is augmented with an interaction reference that the
AS associates with the ongoing request created in (2) and
referenced in (4).  The callback URL is also augmented with a hash
of the security information provided in (2) and (3).  The RC loads
the verification information from (2) and (3) from the session
created in (1).  The RC interaction-hash based on this information
and continues only if the hash validates.  Note that the RC needs
to ensure that the parameters for the incoming request match those
that it is expecting from the session created in (1).  The RC also
needs to be prepared for the RQ never being returned to the RC and
handle time outs appropriately.
Paragraph (version A):
The RC loads the continuation information from (3) and sends the
interaction reference from (7) in a request to continue-after-
interaction.  The AS validates the interaction reference ensuring
that the reference is associated with the request being continued.
Paragraph (version A):
In this example flow, the RC is a device that is capable of
presenting a short, human-readable code to the user and directing the
user to enter that code at a known URL.  The RC is not capable of
presenting an arbitrary URL to the user, nor is it capable of
accepting incoming HTTP requests from the user's browser.  The RC
polls the AS while it is waiting for the RO to authorize the request.
The user's interaction is assumed to occur on a secondary device.  In
this example it is assumed that the user is both the RQ and RO,
though the user is not assumed to be interacting with the RC through
the same web browser used for interaction at the AS.
Paragraph (version A):
The RC request.  The RC indicates that it can request-interact-
usercode.
Paragraph (version A):
The AS determines that interaction is needed and response with a
response-interact-usercode.  This could optionally include a URL
to direct the user to, but this URL should be static and so could
be configured in the RC's documentation.  The AS also includes
information the RC will need to response-continue in (8) and (10).
The AS associates this continuation information with an ongoing
request that will be referenced in (4), (6), (8), and (10).
Paragraph (version A):
The RC stores the continuation information from (2) for use in (8)
and (10).  The RC then interaction-redirect given by the AS in
(2).
Paragraph (version A):
The user's directs their browser to the user code URL.  This URL
is stable and can be communicated via the RC's documentation, the
AS documentation, or the RC software itself.  Since it is assumed
that the RO will interact with the AS through a secondary device,
the RC does not provide a mechanism to launch the RO's browser at
this URL.
Paragraph (version A):
If the access request has not yet been authorized by the RO in
(6), the AS responds to the RC to response-continue at a future
time through additional polled continuation requests.  This
response can include updated continuation information as well as
information regarding how long the RC should wait before calling
again.  The RC replaces its stored continuation information from
the previous response (2).  Note that the AS may need to determine
that the RO has not approved the request in a sufficient amount of
time and return an appropriate error to the RC.
Paragraph (version A):
The RC continues to continue-poll with the new continuation
information in (9).
Paragraph (version B):
When the AS is done interacting with the user, the AS interaction-
callback to the client instance using the callback URL provided in
(2).  The callback URL is augmented with an interaction reference
that the AS associates with the ongoing request created in (2) and
referenced in (4).  The callback URL is also augmented with a hash
of the security information provided in (2) and (3).  The client
instance loads the verification information from (2) and (3) from
the session created in (1).  The client instance interaction-hash
based on this information and continues only if the hash
validates.  Note that the client instance needs to ensure that the
parameters for the incoming request match those that it is
expecting from the session created in (1).  The client instance
also needs to be prepared for the RQ never being returned to the
client instance and handle time outs appropriately.
Paragraph (version B):
The client instance loads the continuation information from (3)
and sends the interaction reference from (7) in a request to
continue-after-interaction.  The AS validates the interaction
reference ensuring that the reference is associated with the
request being continued.
Paragraph (version B):
The client instance request.  The client instance indicates that
it can request-interact-usercode.
Paragraph (version B):
If the access request has not yet been authorized by the RO in
(6), the AS responds to the client instance to response-continue
at a future time through additional polled continuation requests.
This response can include updated continuation information as well
as information regarding how long the client instance should wait
before calling again.  The client instance replaces its stored
continuation information from the previous response (2).  Note
that the AS may need to determine that the RO has not approved the
request in a sufficient amount of time and return an appropriate
error to the client instance.
Paragraph (version B):
The client instance continues to continue-poll with the new
continuation information in (9).
Paragraph (version A):
In this example flow, the RQ and RO roles are fulfilled by different
parties, and the RO does not interact with the RC.  The AS reaches
out asynchronously to the RO during the request process to gather the
RO's authorization for the RC's request.  The RC polls the AS while
it is waiting for the RO to authorize the request.
Paragraph (version A):
The RC request.  The RC does not send any interactions modes to
the server, indicating that it does not expect to interact with
the RO.  The RC can also signal which RO it requires authorization
from, if known, by using the request-user.
Paragraph (version A):
The AS determines that interaction is needed, but the RC cannot
interact with the RO.  The AS response with the information the RC
will need to response-continue in (6) and (8), including a signal
that the RC should wait before checking the status of the request
again.  The AS associates this continuation information with an
ongoing request that will be referenced in (3), (4), (5), (6), and
(8).
Paragraph (version A):
The RO authorizes the pending request from the RC.
Paragraph (version A):
If the access request has not yet been authorized by the RO in
(6), the AS responds to the RC to response-continue at a future
time through additional polling.  This response can include
refreshed credentials as well as information regarding how long
the RC should wait before calling again.  The RC replaces its
stored continuation information from the previous response (2).
Note that the AS may need to determine that the RO has not
approved the request in a sufficient amount of time and return an
appropriate error to the RC.
Paragraph (version A):
The RC continues to continue-poll with the new continuation
information from (7).
Paragraph (version A):
In this example flow, the AS policy allows the RC to make a call on
its own behalf, without the need for a RO to be involved at runtime
to approve the decision.  Since there is no explicit RO, the RC does
not interact with an RO.
Paragraph (version A):
The RC request.  The RC does not send any interactions modes to
the server.
Paragraph (version A):
The AS determines that the request is been authorized, the AS
grants access to the information in the form of response-token and
response-subject to the RC.
Paragraph (version A):
In this example flow, the RC receives an access token to access a
resource server through some valid GNAP process.  The RC uses that
token at the RS for some time, but eventually the access token
expires.  The RC then gets a new access token by rotating the expired
access token at the AS using the token's management URL.
Paragraph (version A):
The RC request.
Paragraph (version A):
The RC use-access-token to the RS.  The RS validates the token and
returns an appropriate response for the API.
Paragraph (version A):
When the access token is expired, the RS responds to the RC with
an error.
Paragraph (version A):
The RC calls the token management URI returned in (2) to rotate-
access-token.  The RC presents the access token as well as the
appropriate key.
Paragraph (version A):
The AS validates the rotation request including the signature and
keys presented in (5) and returns a response-token-single.  The
response includes a new access token and can also include updated
token management information, which the RC will store in place of
the values returned in (2).
Paragraph (version A):
To start a request, the RC sends RFC8259 document with an object as
its root.  Each member of the request object represents a different
aspect of the RC's request.  Each field is described in detail in a
section below.
Paragraph (version A):
Describes the rights that the RC is requesting for one or more
access tokens to be used at RS's.
Paragraph (version A):
Describes the information about the RO that the RC is requesting
to be returned directly in the response from the AS.
Paragraph (version A):
Describes the RC that is making this request, including the key
that the RC will use to protect this request and any continuation
requests at the AS and any user-facing information about the RC
used in interactions at the AS.
Paragraph (version A):
Describes the modes that the RC has for allowing the RO to
interact with the AS and modes for the RC to receive updates when
interaction is complete.
Paragraph (version A):
Identifies named extension capabilities that the RC can use,
signaling to the AS which extensions it can use.
Paragraph (version A):
Identifies a previously-existing grant that the RC is extending
with this request.
Paragraph (version B):
The AS determines that interaction is needed, but the client
instance cannot interact with the RO.  The AS response with the
information the client instance will need to response-continue in
(6) and (8), including a signal that the client instance should
wait before checking the status of the request again.  The AS
associates this continuation information with an ongoing request
that will be referenced in (3), (4), (5), (6), and (8).
Paragraph (version B):
The RO authorizes the pending request from the client instance.
Paragraph (version B):
The client instance continues to continue-poll with the new
continuation information from (7).
Paragraph (version A):
If the RC is requesting one or more access tokens for the purpose of
accessing an API, the RC MUST include a "resources" field.  This
field MUST be an array (for a request-resource-single) or an object
(for request-resource-multiple), as described in the following
sections.
Paragraph (version A):
When requesting an access token, the RC MUST send a "resources" field
containing a JSON array.  The elements of the JSON array represent
rights of access that the RC is requesting in the access token.  The
requested access is the sum of all elements within the array.
Paragraph (version A):
The RC declares what access it wants to associated with the resulting
access token using objects that describe multiple dimensions of
access.  Each object contains a "type" property that determines the
type of API that the RC is calling.
Paragraph (version A):
The types of actions the RC will take at the RS as an array of
strings.  For example, an RC asking for a combination of "read"
and "write" access.
Paragraph (version A):
The kinds of data available to the RC at the RS's API as an array
of strings.  For example, an RC asking for access to raw "image"
data and "metadata" at a photograph API.
Paragraph (version A):
The following non-normative example shows the use of both common and
API-specific fields as part of two different access "type" values.
Paragraph (version A):
If this request is approved, the response-token-single will include
the sum of both of the requested types of access.
Paragraph (version A):
Instead of sending an request-resource-single, a RC MAY send a string
known to the AS or RS representing the access being requested.  Each
string SHOULD correspond to a specific expanded object representation
at the AS.
Paragraph (version A):
This functionality is similar in practice to OAuth 2's "scope"
parameter RFC6749, where a single string represents the set of access
rights requested by the RC.  As such, the reference string could
contain any valid OAuth 2 scope value as in example-oauth2.  Note
that the reference string here is not bound to the same character
restrictions as in OAuth 2's "scope" definition.
Paragraph (version A):
A single "resources" array MAY include both object-type and string-
type resource items.
Paragraph (version A):
When requesting multiple access tokens, the resources field is a JSON
object.  The names of the JSON object fields are token identifiers
chosen by the RC, and MAY be any valid string.  The values of the
JSON object fields are JSON arrays representing a single access token
request, as specified in request-resource-single.
Paragraph (version B):
The access requested for a given object when using these fields is
the cross-product of all fields of the object.  That is to say, the
object represents a request for all "action" values listed within the
object to be used at all "locations" values listed within the object
for all "datatype" values listed within the object.  Assuming the
request above was granted, the RC could assume that it would be able
to do a "read" action against the "images" on the first server as
well as a "delete" action on the "metadata" of the second server, or
any other combination of these fields, using the same access token.
Paragraph (version B):
To request a different combination of access, such as requesting one
"action" against one "location" and a different "action" against a
different "location", the RC can include multiple separate objects in
the "resources" array.  The following non-normative example uses the
same fictitious "photo-api" type definition to request a single
access token with more specifically targeted access rights by using
two discrete objects within the request.
Paragraph (version B):
The access requested here is for "read" access to "images" on one
server while simultaneously requesting "write" and "delete" access
for "metadata" on a different server, but importantly without
requesting "write" or "delete" access to "images" on the first
server.
Paragraph (version B):
It is anticipated that API designers will use a combination of common
fields defined in this specification as well as fields specific to
the API itself.  The following non-normative example shows the use of
both common and API-specific fields as part of two different
fictitious API "type" values.  The first access request includes the
"actions", "locations", and "datatypes" fields specified here as well
as the API-specific "geolocation" field.  The second access request
includes the "actions" and "identifier" fields specified here as well
as the API-specific "currency" field.
Paragraph (version B):
If this request is approved, the response-token-single's access
rights will be the union of the requested types of access for each of
the two APIs, just as above.
Paragraph (version B):
This value is opaque to the client instance and MAY be any valid JSON
string, and therefore could include spaces, unicode characters, and
properly escaped string sequences.  However, in some situations the
value is intended to be seen and understood by the client software's
developer.  In such cases, the API designer choosing any such human-
readable strings SHOULD take steps to ensure the string values are
not easily confused by a developer, such as by limiting the strings
to easily disambiguated characters.
Paragraph (version B):
A single "resources" array MAY include both object-type and string-
type resource items.  In this non-normative example, the RC is
requesting access to a "photo-api" and "financial-transaction" API
type as well as the reference values of "read", "dolphin-metadata",
and "some other thing".
Paragraph (version B):
The requested access is the union of all elements of the array,
including both objects and reference strings.
Paragraph (version A):
While the AS is ultimately in control of how tokens are returned and
bound to the RC, sometimes the RC has context about what it can
support that can affect the AS's response.  This specification
defines several flags that are passed as request-resource-reference.
Paragraph (version A):
The RC wishes to support multiple simultaneous access tokens
through the token rotation process.  When the RC rotate-access-
token, the AS does not invalidate the previous access token.  The
old access token continues to remain valid until such time as it
expires or is revoked through other means.
Paragraph (version A):
In this non-normative example, the requested access token is to be
bound to the client's key and should be kept during rotation.
Paragraph (version A):
If the RC is requesting information about the RO from the AS, it
sends a "subject" field as a JSON object.  This object MAY contain
the following fields (or additional fields defined in IANA).
Paragraph (version A):
When sending a non-continuation request to the AS, the RC MUST
identify itself by including the "client" field of the request and by
signing the request as described in binding-keys.  Note that for a
continue-request, the RC instance is identified by its association
with the request being continued and so this field is not sent under
those circumstances.
Paragraph (version A):
When RC information is sent by value, the "client" field of the
request consists of a JSON object with the following fields.
Paragraph (version A):
The public key of the RC to be used in this request as described
in request-key.  This field is REQUIRED.
Paragraph (version A):
An identifier string that the AS can use to identify the software
comprising this instance of the RC.  The contents and format of
this field are up to the AS.  This field is OPTIONAL.
Paragraph (version B):
When client instance information is sent by value, the "client" field
of the request consists of a JSON object with the following fields.
Paragraph (version A):
The RC MUST prove possession of any presented key by the "proof"
mechanism associated with the key in the request.  Proof types are
defined in IANA and an initial set of methods is described in
binding-keys.
Paragraph (version A):
Note that the AS MAY know the RC's public key ahead of time, and the
AS MAY apply different policies to the request depending on what has
been registered against that key.  If the same public key is sent by
value on subsequent access requests, the AS SHOULD treat these
requests as coming from the same RC software instance for purposes of
identification, authentication, and policy application.  If the AS
does not know the RC's public key ahead of time, the AS MAY accept or
reject the request based on AS policy, attestations within the client
request, and other mechanisms.
Paragraph (version A):
If the RC has an instance identifier that the AS can use to determine
appropriate key information, the RC can send this value in the
"instance_id" field.  The instance identifier MAY be assigned to an
RC instance at runtime through the response-dynamic-handles or MAY be
obtained in another fashion, such as a static registration process at
the AS.
Paragraph (version A):
An identifier string that the AS can use to identify the
particular instance of this RC.  The content and structure of this
identifier is opaque to the RC.
Paragraph (version A):
If there are no additional fields to send, the RC MAY send the
instance identifier as a direct reference value in lieu of the
object.
Paragraph (version A):
If the RC instance is identified in this manner, the registered key
for the RC MAY be a symmetric key known to the AS.  The RC MUST NOT
send a symmetric key by value in the request, as doing so would
expose the key directly instead of proving possession of it.
Paragraph (version A):
The RC key MUST be a public key in at least one supported format and
MUST be applicable to the proofing mechanism used in the request.  If
the key is sent in multiple formats, all the keys MUST be the same.
The key presented in this field MUST be the key used to sign the
request.
Paragraph (version A):
The form of proof that the RC will use when presenting the key to
the AS.  The valid values of this field and the processing
requirements for each are detailed in binding-keys.  This field is
REQUIRED.
Paragraph (version A):
If the RC has additional information to display to the RO during any
interactions at the AS, it MAY send that information in the "display"
field.  This field is a JSON object that declares information to
present to the RO during any interactive sequences.
Paragraph (version A):
The AS SHOULD use these values during interaction with the RO.  The
values are for informational purposes only and MUST NOT be taken as
authentic proof of the RC's identity or source.  The AS MAY restrict
display values to specific RC instances, as identified by their keys
in request-client.
Paragraph (version A):
If the presented key is known to the AS and is associated with a
single instance of the RC software, the process of presenting a key
and proving possession of that key is sufficient to authenticate the
RC to the AS.  The AS MAY associate policies with the RC software
identified by this key, such as limiting which resources can be
requested and which interaction methods can be used.  For example,
only specific RCs with certain known keys might be trusted with
access tokens without the AS interacting directly with the RO as in
example-no-user.
Paragraph (version A):
The presentation of a key allows the AS to strongly associate
multiple successive requests from the same RC with each other.  This
is true when the AS knows the key ahead of time and can use the key
to authenticate the RC software, but also if the key is ephemeral and
created just for this series of requests.  As such the AS MAY allow
for RCs to make requests with unknown keys.  This pattern allows for
ephemeral RCs, such as single-page applications, and RCs with many
individual instances, such as mobile applications, to generate their
own key pairs and use them within the protocol without having to go
through a separate registration step.  The AS MAY limit which
capabilities are made available to RCs with unknown keys.  For
example, the AS could have a policy saying that only previously-
registered RCs can request particular resources, or that all RCs with
unknown keys have to be interactively approved by an RO.
Paragraph (version A):
If the RC knows the identity of the RQ through one or more
identifiers or assertions, the RC MAY send that information to the AS
in the "user" field.  The RC MAY pass this information by value or by
reference.
Paragraph (version B):
If the client instance has additional information to display to the
RO during any interactions at the AS, it MAY send that information in
the "display" field.  This field is a JSON object that declares
information to present to the RO during any interactive sequences.
Paragraph (version B):
If the presented key is known to the AS and is associated with a
single instance of the client software, the process of presenting a
key and proving possession of that key is sufficient to authenticate
the client instance to the AS.  The AS MAY associate policies with
the client instance identified by this key, such as limiting which
resources can be requested and which interaction methods can be used.
For example, only specific client instances with certain known keys
might be trusted with access tokens without the AS interacting
directly with the RO as in example-no-user.
Paragraph (version B):
The presentation of a key allows the AS to strongly associate
multiple successive requests from the same client instance with each
other.  This is true when the AS knows the key ahead of time and can
use the key to authenticate the client instance, but also if the key
is ephemeral and created just for this series of requests.  As such
the AS MAY allow for client instances to make requests with unknown
keys.  This pattern allows for ephemeral client instances, such as
single-page applications, and client software with many individual
long-lived instances, such as mobile applications, to generate key
pairs per instance and use the keys within the protocol without
having to go through a separate registration step.  The AS MAY limit
which capabilities are made available to client instances with
unknown keys.  For example, the AS could have a policy saying that
only previously-registered client instances can request particular
resources, or that all client instances with unknown keys have to be
interactively approved by an RO.
Paragraph (version A):
If the AS trusts the RC to present verifiable assertions, the AS MAY
decide, based on its policy, to skip interaction with the RO, even if
the RC provides one or more interaction modes in its request.
Paragraph (version A):
User reference identifiers can be dynamically response-dynamic-
handles to allow the RC to represent the same RQ to the AS over
subsequent requests.
Paragraph (version A):
If the RC has a reference for the RQ at this AS, the RC MAY pass that
reference as a string.  The format of this string is opaque to the
RC.
Paragraph (version A):
User reference identifiers are not intended to be human-readable user
identifiers or structured assertions.  For the RC to send either of
these, use the full request-user instead.
Paragraph (version A):
Many times, the AS will require interaction with the RO in order to
approve a requested delegation to the RC for both resources and
direct claim information.  Many times the RQ using the RC is the same
person as the RO, and the RC can directly drive interaction with the
AS by redirecting the RQ on the same device, or by launching an
application.  Other times, the RC can provide information to start
the RO's interaction on a secondary device, or the RC will wait for
the RO to approve the request asynchronously.  The RC could also be
signaled that interaction has completed by the AS making callbacks.
To facilitate all of these modes, the RC declares the means that it
can interact using the "interact" field.
Paragraph (version A):
Indicates that the RC can direct the RQ to an arbitrary URL at the
AS for interaction.
Paragraph (version A):
Indicates that the RC can launch an application on the RQ's device
for interaction.
Paragraph (version A):
Indicates that the RC can receive a callback from the AS after
interaction with the RO has concluded.
Paragraph (version A):
Indicates that the RC can communicate a human-readable short code
to the RQ for use with a stable URL at the AS.
Paragraph (version A):
In this non-normative example, the RC is indicating that it can
request-interact-redirect the RQ to an arbitrary URL and can receive
a request-interact-callback through a browser request.
Paragraph (version A):
In this non-normative example, the RC is indicating that it can
display a request-interact-usercode and direct the RQ to an request-
interact-short 255 characters, but it cannot accept a callback.
Paragraph (version A):
If the RC does not provide a suitable interaction mechanism, the AS
cannot contact the RO asynchronously, and the AS determines that
interaction is required, then the AS SHOULD return an error since the
RC will be unable to complete the request without authorization.
Paragraph (version A):
The AS SHOULD apply suitable timeouts to any interaction mechanisms
provided, including user codes and redirection URLs.  The RC SHOULD
apply suitable timeouts to any callback URLs.
Paragraph (version A):
If the RC is capable of directing the RQ to a URL defined by the AS
at runtime, the RC indicates this by sending the "redirect" field
with the boolean value "true".  The means by which the RC will
activate this URL is out of scope of this specification, but common
methods include an HTTP redirect, launching a browser on the RQ's
device, providing a scannable image encoding, and printing out a URL
to an interactive console.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns a redirect interaction response response-interact-redirect.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns a redirect interaction response with short URL response-
interact-redirect.
Paragraph (version A):
If the RC can open a URL associated with an application on the RQ's
device, the RC indicates this by sending the "app" field with boolean
value "true".  The means by which the RC determines the application
to open with this URL are out of scope of this specification.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns an app interaction response with an app URL payload response-
interact-app.
Paragraph (version A):
If the RC is capable of receiving a message from the AS indicating
that the RO has completed their interaction, the RC indicates this by
sending the "callback" field.  The value of this field is an object
containing the following members.
Paragraph (version A):
REQUIRED.  Unique value to be used in the calculation of the
"hash" query parameter sent to the callback URL, must be
sufficiently random to be unguessable by an attacker.  MUST be
generated by the RC as a unique value for this request.
Paragraph (version A):
REQUIRED.  The callback method that the AS will use to contact the
RC.  Valid values include "redirect" request-interact-callback-
redirect and "push" request-interact-callback-push, with other
values defined by IANA.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns a nonce for use in validating response-interact-callback.
Requests to the callback URI MUST be processed as described in
interaction-finalize, and the AS MUST require presentation of an
interaction callback reference as described in continue-after-
interaction.
Paragraph (version A):
A callback "method" value of "redirect" indicates that the RC will
expect a call from the RO's browser using the HTTP method GET as
described in interaction-callback.
Paragraph (version A):
Requests to the callback URI MUST be processed by the RC as described
in interaction-callback.
Paragraph (version A):
Since the incoming request to the callback URL is from the RO's
browser, this method is usually used when the RO and RQ are the same
entity.  As such, the RC MUST ensure the RQ is present on the request
to prevent substitution attacks.
Paragraph (version A):
A callback "method" value of "push" indicates that the RC will expect
a call from the AS directly using the HTTP method POST as described
in interaction-pushback.
Paragraph (version A):
Requests to the callback URI MUST be processed by the RC as described
in interaction-pushback.
Paragraph (version A):
Since the incoming request to the callback URL is from the AS and not
from the RO's browser, the RC MUST NOT require the RQ to be present
on the incoming HTTP request.
Paragraph (version A):
If the RC is capable of displaying or otherwise communicating a
short, human-entered code to the RO, the RC indicates this by sending
the "user_code" field with the boolean value "true".  This code is to
be entered at a static URL that does not change at runtime, as
described in response-interact-usercode.
Paragraph (version A):
If this interaction mode is supported for this RC and request, the AS
returns a user code and interaction URL as specified in interaction-
usercode.
Paragraph (version A):
If the RC knows the RQ's locale and language preferences, the RC can
send this information to the AS using the "ui_locales" field with an
array of locale strings as defined by RFC5646.
Paragraph (version B):
Requests to the callback URI MUST be processed by the client instance
as described in interaction-callback.
Paragraph (version B):
Requests to the callback URI MUST be processed by the client instance
as described in interaction-pushback.
Paragraph (version A):
If the RC supports extension capabilities, it MAY present them to the
AS in the "capabilities" field.  This field is an array of strings
representing specific extensions and capabilities, as defined by
IANA.
Paragraph (version A):
If the RC has a reference handle from a previously granted request,
it MAY send that reference in the "existing_grant" field.  This field
is a single string consisting of the "value" of the "access_token"
returned in a previous request's response-continue.
Paragraph (version A):
A single access token that the RC can use to call the RS on behalf
of the RO.
Paragraph (version A):
Multiple named access tokens that the RC can use to call the RS on
behalf of the RO.
Paragraph (version A):
An identifier this RC instance can use to identify itself when
making future requests.
Paragraph (version A):
An identifier this RC instance can use to identify its current RQ
when making future requests.
Paragraph (version A):
REQUIRED.  The URI at which the RC can make continuation requests.
This URI MAY vary per request, or MAY be stable at the AS if the
AS includes an access token.  The RC MUST use this value exactly
as given when making a continue-request.
Paragraph (version A):
RECOMMENDED.  The amount of time in integer seconds the RC SHOULD
wait after receiving this continuation handle and calling the URI.
Paragraph (version A):
This field SHOULD be returned when interaction is expected, to allow
the RC to follow up after interaction has been concluded.
Paragraph (version A):
If the AS has successfully granted one or more access tokens to the
RC, the AS responds with either the "access_token" or the
"multiple_access_token" field.  The AS MUST NOT respond with both the
"access_token" and "multiple_access_token" fields.
Paragraph (version A):
If the RC has requested a single access token and the AS has granted
that access token, the AS responds with the "access_token" field.
The value of this field is an object with the following properties.
Paragraph (version A):
REQUIRED.  The value of the access token as a string.  The value
is opaque to the RC.  The value SHOULD be limited to ASCII
characters to facilitate transmission over HTTP headers within
other protocols without requiring additional encoding.
Paragraph (version A):
OPTIONAL.  The management URI for this access token.  If provided,
the RC MAY manage its access token as described in token-
management.  This management URI is a function of the AS and is
separate from the RS the RC is requesting access to.  This URI
MUST NOT include the access token value and SHOULD be different
for each access token issued in a request.
Paragraph (version A):
RECOMMENDED.  A description of the rights associated with this
access token, as defined in request-resource-single.  If included,
this MUST reflect the rights associated with the issued access
token.  These rights MAY vary from what was requested by the RC.
Paragraph (version A):
OPTIONAL.  The number of seconds in which the access will expire.
The RC MUST NOT use the access token past this time.  An RS MUST
NOT accept an access token past this time.  Note that the access
token MAY be revoked by the AS or RS at any point prior to its
expiration.
Paragraph (version A):
REQUIRED.  The key that the token is bound to.  If the boolean
value "true" is used, the token is bound to the request-key in its
request for access.  If the boolean value "false" is used, the
token is a bearer token with no key bound to it.  Otherwise, the
key MUST be an object or string in a format described in request-
key, describing a public key to which the RC can use the
associated private key.  The RC MUST be able to dereference or
process the key information in order to be able to sign the
request.
Paragraph (version A):
The following non-normative example shows a single access token bound
to the RC's key, which was presented using the detached-jws binding
method.
Paragraph (version A):
If the RC request-resource-multiple, the AS MUST NOT respond with a
single access token structure unless the RC sends the "split_token"
flag as described in request-resource-flag.
Paragraph (version A):
If the RC has requested multiple access tokens and the AS has granted
at least one of them, the AS responds with the
"multiple_access_tokens" field.  The value of this field is a JSON
object, and the property names correspond to the token identifiers
chosen by the RC in the request-resource-multiple.  The values of the
properties of this object are access tokens as described in response-
token-single.
Paragraph (version A):
Each access token corresponds to the named resources arrays in the
RC's request-resource-multiple.
Paragraph (version B):
If the client instance has requested a single access token and the AS
has granted that access token, the AS responds with the
"access_token" field.  The value of this field is an object with the
following properties.
Paragraph (version A):
If the RC request-resource-single, the AS MUST NOT respond with the
multiple access token structure unless the RC sends the "split_token"
flag as described in request-resource-flag.
Paragraph (version A):
If the RC has indicated a request-interact, and the AS has determined
that interaction is both supported and necessary, the AS responds to
the RC with any of the following values in the "interact" field of
the response.  There is no preference order for interaction modes in
the response, and it is up to the RC to determine which ones to use.
All supported interaction methods are included in the same "interact"
object.
Paragraph (version A):
Callback to an RC URL after interaction is completed.
Paragraph (version A):
The AS MUST NOT respond with any interaction mode that the RC did not
indicate in its request.  The AS MUST NOT respond with any
interaction mode that the AS does not support.  Since interaction
responses include secret or unique information, the AS SHOULD respond
to each interaction mode only once in an ongoing request,
particularly if the RC continue-modify.
Paragraph (version A):
If the RC indicates that it can request-interact-redirect and the AS
supports this mode for the RC's request, the AS responds with the
"redirect" field, which is a string containing the URL to direct the
RQ to.  This URL MUST be unique for the request and MUST NOT contain
any security-sensitive information.
Paragraph (version A):
The RC sends the RQ to the URL to interact with the AS.  The RC MUST
NOT alter the URL in any way.  The means for the RC to send the RQ to
this URL is out of scope of this specification, but common methods
include an HTTP redirect, launching the system browser, displaying a
scannable code, or printing out the URL in an interactive console.
Paragraph (version A):
If the RC indicates that it can request-interact-app and the AS
supports this mode for the RC's request, the AS responds with the
"app" field, which is a string containing the URL to direct the RQ
to.  This URL MUST be unique for the request and MUST NOT contain any
security-sensitive information.
Paragraph (version A):
The RC launches the URL as appropriate on its platform, and the means
for the RC to launch this URL is out of scope of this specification.
The RC MUST NOT alter the URL in any way.  The RC MAY attempt to
detect if an installed application will service the URL being sent
before attempting to launch the application URL.
Paragraph (version A):
If the RC indicates that it can request-interact-callback and the AS
supports this mode for the RC's request, the AS responds with a
"callback" field containing a nonce that the RC will use in
validating the callback as defined in interaction-callback.
Paragraph (version A):
When the RO completes interaction at the AS, the AS MUST call the
RC's callback URL using the method indicated in the request-interact-
callback as described in interaction-callback.
Paragraph (version A):
If the AS returns a "callback" nonce, the RC MUST NOT continue a
grant request before it receives the associated interaction reference
on the callback URI.
Paragraph (version A):
If the RC indicates that it can request-interact-usercode and the AS
supports this mode for the RC's request, the AS responds with a
"user_code" field.  This field is an object that contains the
following members.
Paragraph (version B):
If the client instance has indicated a request-interact, and the AS
has determined that interaction is both supported and necessary, the
AS responds to the client instance with any of the following values
in the "interact" field of the response.  There is no preference
order for interaction modes in the response, and it is up to the
client instance to determine which ones to use.  All supported
interaction methods are included in the same "interact" object.
Paragraph (version B):
The AS MUST NOT respond with any interaction mode that the client
instance did not indicate in its request.  The AS MUST NOT respond
with any interaction mode that the AS does not support.  Since
interaction responses include secret or unique information, the AS
SHOULD respond to each interaction mode only once in an ongoing
request, particularly if the client instance continue-modify.
Paragraph (version A):
RECOMMENDED.  The interaction URL that the RC will direct the RO
to.  This URL MUST be stable at the AS such that RCs can be
statically configured with it.
Paragraph (version A):
The RC MUST communicate the "code" to the RQ in some fashion, such as
displaying it on a screen or reading it out audibly.  The "code" is a
one-time-use credential that the AS uses to identify the pending
request from the RC.  When the RO interaction-usercode into the AS,
the AS MUST determine the pending request that it was associated
with.  If the AS does not recognize the entered code, the AS MUST
display an error to the user.  If the AS detects too many
unrecognized codes entered, it SHOULD display an error to the user.
Paragraph (version A):
The RC SHOULD also communicate the URL if possible to facilitate user
interaction, but since the URL should be stable, the RC should be
able to safely decide to not display this value.  As this interaction
mode is designed to facilitate interaction via a secondary device, it
is not expected that the RC redirect the RQ to the URL given here at
runtime.  Consequently, the URL needs to be stable enough that a RC
could be statically configured with it, perhaps referring the RQ to
the URL via documentation instead of through an interactive means.
If the RC is capable of communicating an arbitrary URL to the RQ,
such as through a scannable code, the RC can use the request-
interact-redirect mode for this purpose instead of or in addition to
the user code mode.
Paragraph (version A):
If information about the RO is requested and the AS grants the RC
access to that data, the AS returns the approved information in the
"subject" response field.  This field is an object with the following
OPTIONAL properties.
Paragraph (version A):
Timestamp as an ISO8610 date string, indicating when the
identified account was last updated.  The RC MAY use this value to
determine if it needs to request updated profile information
through an identity API.  The definition of such an identity API
is out of scope for this specification.
Paragraph (version A):
Subject identifiers returned by the AS SHOULD uniquely identify the
RO at the AS.  Some forms of subject identifier are opaque to the RC
(such as the subject of an issuer and subject pair), while others
forms (such as email address and phone number) are intended to allow
the RC to correlate the identifier with other account information at
the RC.  The RC MUST NOT request or use any returned subject
identifiers for communication purposes (see request-subject).  That
is, a subject identifier returned in the format of an email address
or a phone number only identifies the RO to the AS and does not
indicate that the AS has validated that the represented email address
or phone number in the identifier is suitable for communication with
the current user.  To get such information, the RC MUST use an
identity protocol to request and receive additional identity claims.
While request-oidc-claims specifies one such method, other identity
protocols could also be used on top of GNAP to convey this
information and the details of an identity protocol and associated
schema are outside the scope of this specification.
Paragraph (version A):
Many parts of the RC's request can be passed as either a value or a
reference.  The use of a reference in place of a value allows for a
client to optimize requests to the AS.
Paragraph (version A):
Some references, such as for the request-instance or the request-
resource-reference, can be managed statically through an admin
console or developer portal provided by the AS or RS.  The developer
of the RC can include these values in their code for a more efficient
and compact request.
Paragraph (version A):
If desired, the AS MAY also generate and return some of these
references dynamically to the RC in its response to facilitate
multiple interactions with the same software.  The RC SHOULD use
these references in future requests in lieu of sending the associated
data value.  These handles are intended to be used on future
requests.
Paragraph (version A):
Dynamically generated handles are string values that MUST be
protected by the RC as secrets.  Handle values MUST be unguessable
and MUST NOT contain any sensitive information.  Handle values are
opaque to the RC.
Paragraph (version B):
Many parts of the client instance's request can be passed as either a
value or a reference.  The use of a reference in place of a value
allows for a client instance to optimize requests to the AS.
Paragraph (version A):
A string value used to represent the information in the "client"
object that the RC can use in a future request, as described in
request-instance.
Paragraph (version A):
A string value used to represent the current user.  The RC can use
in a future request, as described in request-user-reference.
Paragraph (version A):
If the AS determines that the request cannot be issued for any
reason, it responds to the RC with an error message.
Paragraph (version A):
The RC did not respect the timeout in the wait response.
Paragraph (version A):
If the RC request-interact, and the AS determines that interaction is
required and responds to one or more of the RC's interaction modes,
the RC SHOULD initiate one of the returned response-interact.
Paragraph (version A):
When the RO is directed to the AS through the response-interact-
redirect mode, the AS can interact with the RO through their web
browser to authenticate the user as an RO and gather their consent.
Note that since the RC does not add any parameters to the URL, the AS
MUST determine the grant request being referenced from the URL value
itself.  If the URL cannot be associated with a currently active
request, the AS MUST display an error to the RO and MUST NOT attempt
to redirect the RO back to any RC even if a request-interact-
callback.
Paragraph (version A):
The interaction URL MUST be reachable from the RO's browser, though
note that the RO MAY open the URL on a separate device from the RC
itself.  The interaction URL MUST be accessible from an HTTP GET
request, and MUST be protected by HTTPS or equivalent means.
Paragraph (version A):
With this method, it is common for the RO to be the same party as the
RQ, since the RC has to communicate the redirection URI to the RQ.
Paragraph (version A):
When the RO is directed to the AS through the response-interact-
usercode mode, the AS can interact with the RO through their web
browser to collect the user code, authenticate the user as an RO, and
gather their consent.  Note that since the URL itself is static, the
AS MUST determine the grant request being referenced from the user
code value itself.  If the user code cannot be associated with a
currently active request, the AS MUST display an error to the RO and
MUST NOT attempt to redirect the RO back to any RC even if a request-
interact-callback.
Paragraph (version A):
The user code URL MUST be reachable from the RO's browser, though
note that the RO MAY open the URL on a separate device from the RC
itself.  The user code URL MUST be accessible from an HTTP GET
request, and MUST be protected by HTTPS or equivalent means.
Paragraph (version A):
While it is common for the RO to be the same party as the RQ, since
the RC has to communicate the user code to someone, there are cases
where the RQ and RO are separate parties and the authorization
happens asynchronously.
Paragraph (version A):
When the RC successfully launches an application through the
response-interact-app, the AS interacts with the RO through that
application to authenticate the user as the RO and gather their
consent.  The details of this interaction are out of scope for this
specification.
Paragraph (version A):
Upon completing an interaction with the RO, if a response-interact-
callback mode is available with the current request, the AS MUST
follow the appropriate method at the end of interaction to allow the
RC to continue.  If this mode is not available, the AS SHOULD
instruct the RO to return to their RC software upon completion.  Note
that these steps still take place in most error cases, such as when
the RO has denied access.  This pattern allows the RC to potentially
recover from the error state without restarting the request from
scratch by modifying its request or providing additional information
directly to the AS.
Paragraph (version A):
The AS MUST calculate a hash value based on the RC and AS nonces and
the interaction reference, as described in interaction-hash.  The RC
will use this value to validate the return call from the AS.
Paragraph (version A):
When using the response-interact-callback with the "redirect" method,
the AS signals to the RC that interaction is complete and the request
can be continued by directing the RO (in their browser) back to the
RC's callback URL sent in request-interact-callback-redirect.
Paragraph (version A):
The AS secures this callback by adding the hash and interaction
reference as query parameters to the RC's callback URL.
Paragraph (version A):
When receiving the request, the RC MUST parse the query parameters to
calculate and validate the hash value as described in interaction-
hash.  If the hash validates, the RC sends a continuation request to
the AS as described in continue-after-interaction using the
interaction reference value received here.
Paragraph (version A):
When using the response-interact-callback with the "push" method, the
AS signals to the RC that interaction is complete and the request can
be continued by sending an HTTP POST request to the RC's callback URL
sent in request-interact-callback-push.
Paragraph (version A):
When receiving the request, the RC MUST parse the JSON object and
validate the hash value as described in interaction-hash.  If the
hash validates, the RC sends a continuation request to the AS as
described in continue-after-interaction using the interaction
reference value received here.
Paragraph (version A):
The "hash" parameter in the request to the RC's callback URL ties the
front channel response to an ongoing request by using values known
only to the parties involved.  This security mechanism allows the RC
to protect itself against several kinds of session fixation and
injection attacks.  The AS MUST always provide this hash, and the RC
MUST validate the hash when received.
Paragraph (version A):
To calculate the "hash" value, the party doing the calculation first
takes the "nonce" value sent by the RC in the request-interact-
callback, the AS's nonce value from response-interact-callback, and
the "interact_ref" sent to the RC's callback URL.  These three values
are concatenated to each other in this order using a single newline
character as a separator between the fields.  There is no padding or
whitespace before or after any of the lines, and no trailing newline
character.
Paragraph (version A):
The party then hashes this string with the appropriate algorithm
based on the "hash_method" parameter of the "callback".  If the
"hash_method" value is not present in the RC's request, the algorithm
defaults to "sha3".
Paragraph (version A):
While it is possible for the AS to return a response with all the
RC's requested information (including response-token and response-
subject), it's more common that the AS and the RC will need to
communicate several times over the lifetime of an access grant.  This
is often part of facilitating user-interaction, but it could also be
used to allow the AS and RC to continue negotiating the parameters of
the request.
Paragraph (version A):
The ability to continue an already-started request allows the RC to
perform several important functions, including presenting additional
information from interaction, modifying the initial request, and
getting the current state of the request.
Paragraph (version A):
For continuation functions that require the RC to send a message
body, the body MUST be a JSON object.
Paragraph (version A):
When the AS responds to the RC's "callback" parameter as in
interaction-callback, this response includes an interaction
reference.  The RC MUST include that value as the field
"interact_ref" in a POST request to the continuation URI.
Paragraph (version A):
Since the interaction reference is a one-time-use value as described
in interaction-callback, if the RC needs to make additional
continuation calls after this request, the RC MUST NOT include the
interaction reference.  If the AS detects an RC submitting the same
interaction reference multiple times, the AS MUST return an error and
SHOULD invalidate the ongoing request.
Paragraph (version A):
With this example, the RC can not make an additional continuation
request because a "continue" field is not included.
Paragraph (version A):
When the RC does not include a "callback" parameter, the RC will
often need to poll the AS until the RO has authorized the request.
To do so, the RC makes a POST request to the continuation URI as in
continue-after-interaction, but does not include a message body.
Paragraph (version A):
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 RC.  The response SHOULD NOT contain response-interact.
Paragraph (version A):
For example, if the request has not yet been authorized by the RO,
the AS could respond by telling the RC to make another continuation
request in the future.  In this example, a new, unique access token
has been issued for the call, which the RC will use in its next
continuation request.
Paragraph (version B):
For continuation functions that require the client instance to send a
message body, the body MUST be a JSON object.
Paragraph (version B):
With this example, the client instance can not make an additional
continuation request because a "continue" field is not included.
Paragraph (version B):
For example, if the request has not yet been authorized by the RO,
the AS could respond by telling the client instance to make another
continuation request in the future.  In this example, a new, unique
access token has been issued for the call, which the client instance
will use in its next continuation request.
Paragraph (version A):
The RC might need to modify an ongoing request, whether or not tokens
have already been issued or claims have already been released.  In
such cases, the RC makes an HTTP PATCH request to the continuation
URI and includes any fields it needs to modify.  Fields that aren't
included in the request are considered unchanged from the original
request.
Paragraph (version A):
The RC MAY include the "interact" field as described in request-
interact.  Inclusion of this field indicates that the RC is capable
of driving interaction with the RO, 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 A):
The AS replaces the previous "resources" from the first request,
allowing the AS to determine if any previously-granted consent
already applies.  In this case, the AS would likely determine that
reducing the breadth of the requested access means that new access
tokens can be issued to the RC.  The AS would likely revoke
previously-issued access tokens that had the greater access rights
associated with them.
Paragraph (version A):
For another example, the RC initially requests read-only access but
later needs to step up its access.  The initial request could look
like this example.
Paragraph (version A):
This allows the RC to make an eventual continuation call.  The RC
later realizes that it now needs "write" access in addition to the
"read" access.  Since this is an expansion of what it asked for
previously, the RC also includes a new interaction section in case
the AS needs to interact with the RO again to gather additional
authorization.  Note that the RC's nonce and callback are different
from the initial request.  Since the original callback was already
used in the initial exchange, and the callback is intended for one-
time-use, a new one needs to be included in order to use the callback
again.
Paragraph (version A):
From here, the AS can determine that the RC is asking for more than
it was previously granted, but since the RC has also provided a
mechanism to interact with the RO, the AS can use that to gather the
additional consent.  The protocol continues as it would with a new
request.  Since the old access tokens are good for a subset of the
rights requested here, the AS might decide to not revoke them.
However, any access tokens granted after this update process are new
access tokens and do not modify the rights of existing access tokens.
Paragraph (version A):
If the RC needs to get the current state of an ongoing grant request,
it makes an HTTP GET request to the continuation URI.  This request
MUST NOT alter the grant request in any fashion, including causing
the issuance of new access tokens or modification of interaction
parameters.
Paragraph (version B):
For another example, the client instance initially requests read-only
access but later needs to step up its access.  The initial request
could look like this example.
Paragraph (version B):
This allows the client instance to make an eventual continuation
call.  The client instance later realizes that it now needs "write"
access in addition to the "read" access.  Since this is an expansion
of what it asked for previously, the client instance also includes a
new interaction section in case the AS needs to interact with the RO
again to gather additional authorization.  Note that the client
instance's nonce and callback are different from the initial request.
Since the original callback was already used in the initial exchange,
and the callback is intended for one-time-use, a new one needs to be
included in order to use the callback again.
Paragraph (version B):
From here, the AS can determine that the client instance is asking
for more than it was previously granted, but since the client
instance has also provided a mechanism to interact with the RO, the
AS can use that to gather the additional consent.  The protocol
continues as it would with a new request.  Since the old access
tokens are good for a subset of the rights requested here, the AS
might decide to not revoke them.  However, any access tokens granted
after this update process are new access tokens and do not modify the
rights of existing access tokens.
Paragraph (version A):
If the RC wishes to cancel an ongoing grant request, it makes an HTTP
DELETE request to the continuation URI.
Paragraph (version A):
If an access token response includes the "manage" parameter as
described in response-token-single, the RC MAY call this URL to
manage the access token with any of the actions defined in the
following sections.  Other actions are undefined by this
specification.
Paragraph (version A):
The access token being managed acts as the access element for its own
management API.  The RC MUST present proof of an appropriate key
along with the access token.
Paragraph (version A):
If the token is a bearer token, the RC MUST present proof of the same
request-key as described in binding-keys.
Paragraph (version A):
The AS MUST validate the proof and assure that it is associated with
either the token itself or the RC the token was issued to, as
appropriate for the token's presentation type.
Paragraph (version A):
The RC makes an HTTP POST to the token management URI, sending the
access token in the appropriate header and signing the request with
the appropriate key.
Paragraph (version A):
The AS validates that the token presented is associated with the
management URL, that the AS issued the token to the given RC, and
that the presented key is appropriate to the token.
Paragraph (version A):
If the access token has expired, the AS SHOULD honor the rotation
request to the token management URL since it is likely that the RC is
attempting to refresh the expired token.  To support this, the AS MAY
apply different lifetimes for the use of the token in management vs.
its use at an RS.  An AS MUST NOT honor a rotation request for an
access token that has been revoked, either by the AS or by the RC
through the revoke-access-token.
Paragraph (version B):
The access token being managed acts as the access element for its own
management API.  The client instance MUST present proof of an
appropriate key along with the access token.
Paragraph (version B):
The AS MUST validate the proof and assure that it is associated with
either the token itself or the client instance the token was issued
to, as appropriate for the token's presentation type.
Paragraph (version A):
If the RC wishes to revoke the access token proactively, such as when
a user indicates to the RC that they no longer wish for it to have
access or the RC application detects that it is being uninstalled,
the RC can use the token management URI to indicate to the AS that
the AS should invalidate the access token for all purposes.
Paragraph (version A):
The RC makes an HTTP DELETE request to the token management URI,
presenting the access token and signing the request with the
appropriate key.
Paragraph (version A):
If the key presented is associated with the token (or the RC, in the
case of a bearer token), the AS MUST invalidate the access token, if
possible, and return an HTTP 204 response code.
Paragraph (version A):
Though the AS MAY revoke an access token at any time for any reason,
the token management function is specifically for the RC's use.  If
the access token has already expired or has been revoked through
other means, the AS SHOULD honor the revocation request to the token
management URL as valid, since the end result is still the token not
being usable.
Paragraph (version A):
The method the RC uses to send an access token to the RS depends on
the value of the "key" and "proof" parameters in response-token-
single.
Paragraph (version B):
If the client instance wishes to revoke the access token proactively,
such as when a user indicates to the client instance that they no
longer wish for it to have access or the client instance application
detects that it is being uninstalled, the client instance can use the
token management URI to indicate to the AS that the AS should
invalidate the access token for all purposes.
Paragraph (version B):
The client instance makes an HTTP DELETE request to the token
management URI, presenting the access token and signing the request
with the appropriate key.
Paragraph (version B):
If the key presented is associated with the token (or the client
instance, in the case of a bearer token), the AS MUST invalidate the
access token, if possible, and return an HTTP 204 response code.
Paragraph (version A):
If the "key" value is the boolean "true", the access token MUST be
sent to the RS using the same key and proofing mechanism that the RC
used in its initial request.
Paragraph (version A):
The header of the JWS MUST contain the "kid" field of the key bound
to this RC for this request.  The JWS header MUST contain an "alg"
field appropriate for the key identified by kid and MUST NOT be
"none".
Paragraph (version A):
The RC presents the JWS as the body of the request along with a
content type of "application/jose".  The AS MUST extract the payload
of the JWS and treat it as the request body for further processing.
Paragraph (version A):
This method is indicated by "mtls" in the "proof" field.  The RC
presents its client certificate during TLS negotiation with the
server (either AS or RS).  The AS or RS takes the thumbprint of the
client certificate presented during mutual TLS negotiation and
compares that thumbprint to the thumbprint presented by the RC
application as described in RFC8705 section 3.
Paragraph (version A):
This method is indicated by "httpsig" in the "proof" field.  The RC
creates an HTTP Signature header as described in I-D.ietf-httpbis-
message-signatures section 4.  The RC MUST calculate and present the
Digest header as defined in RFC3230 and include this header in the
signature.
Paragraph (version A):
By design, the protocol minimizes the need for any pre-flight
discovery.  To begin a request, the RC only needs to know the
endpoint of the AS and which keys it will use to sign the request.
Everything else can be negotiated dynamically in the course of the
protocol.
Paragraph (version A):
REQUIRED.  The full URL of the AS's grant request endpoint.  This
MUST match the URL the RC used to make the discovery request.
Paragraph (version A):
OPTIONAL.  A list of the AS's capabilities.  The values of this
result MAY be used by the RC in the request-capabilities of the
request.
Paragraph (version A):
The information returned from this method is for optimization
purposes only.  The AS MAY deny any request, or any portion of a
request, even if it lists a capability as supported.  For example, a
given RC can be registered with the "mtls" key proofing mechanism,
but the AS also returns other proofing methods, then the AS will deny
a request from that RC using a different proofing mechanism.
Paragraph (version A):
The RC calls the RS with its access token.
Paragraph (version A):
The RS introspects the access token value at the AS.  The RS signs
the request with its own key (not the RC's key or the token's
key).
Paragraph (version A):
The AS validates the token value and the RC's request and returns
the introspection response for the token.
Paragraph (version A):
The RS fulfills the request from the RC.
Paragraph (version A):
Some architectures require an RS to act as an RC and request a
derived access token for a secondary RS.  This internal token is
issued in the context of the incoming access token.
Paragraph (version A):
The RC calls RS1 with an access token.
Paragraph (version A):
RS1 presents that token to the AS to get a derived token for use
at RS2.  RS1 indicates that it has no ability to interact with the
RO.  RS1 signs its request with its own key, not the token's key
or the RC's key.
Paragraph (version A):
RS1 fulfills the call from RC.
Paragraph (version A):
If the RC calls an RS without an access token, or with an invalid
access token, the RS MAY respond to the RC with an authentication
header indicating that GNAP needs to be used to access the resource.
The address of the GNAP endpoint MUST be sent in the "as_uri"
parameter.  The RS MAY additionally return a resource reference that
the RC MAY use in its request-resource.  This resource reference
handle SHOULD be sufficient for at least the action the RC was
attempting to take at the RS.  The RS MAY use the rs-register-
resource-handle to register a new resource handle, or use a handle
that has been pre-configured to represent what the AS is protecting.
The content of this handle is opaque to the RS and the RC.
Paragraph (version A):
The RC then makes a call to the "as_uri" as described in request,
with the value of "resource" as one of the members of a "resources"
array request-resource-single.  The RC MAY request additional
resources and other information, and MAY request multiple access
tokens.
Paragraph (version A):
When user information is passed to the RC, the AS needs to make sure
that it has the permission to do so.