Draft: draft-ietf-gnap-core-protocol

Commentary: The aim is to 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 In various places in the protocol , the terms URI and URL seem to me to be used more or less synonymously . For example , in there is a property in the field , while in there is a member in the field . Another example is the description of the interaction start mode . While in Sections and the term URL is used consistently , in mostly URI is used , but in one sentence URL is used again . Would n't it make sense to make this consistent and always speak of a URL , since I assume that the use of Uniform Resource Names ( URNs ) is not intended ? Or is there a reason why URI is used in some places and URL _ in others ? 
 I ca n't guarantee that all the language is consistent about this , but the differentiation is intentional : in a lot of places , we do mean URI because the resolution of that URI is potentially a local matter for the party at hand . For example , the redirect - based stuff could be various kinds of URIs that are used to switch on some kind of local behavior on the end - user 's system . I anticipate that we mostly need to change everything to URI throughout , and only have a handful of places where we more specifically mean URL . 
 Ok , having looked at this issue a bit more There are places where URI is intentional , like 4.1.3 . Interaction through an Application URI . There are places where URI is provided because it 's the most generic possibility , e.g. " This URI MUST be protected by HTTPS , be hosted on a server local to the RO 's browser ( " localhost " ) , or use an application - specific URI scheme . " ( 2.5.2 ) or " he client instance could launch the URI through the system browser , provide a clickable link , redirect the user through HTTP response codes , or display the URI in a form the end user can use to launch such as a multidimensional barcode . " ( 4.1.1 ) in RAR , locations are defined as URIs : " These strings are typically URIs identifying the location of the RS . " But there are also places where it 's unclear : " The URI MUST be accessible from an HTTP GET request and MUST be protected by HTTPS or equivalent means . " ( effectively that 's an URL ) Most of the examples are URL , even when the field is labeled URI Section 1.5.2 ( user code interaction ) and 3.3.3 use an URL , probably because it 's supposed to be statically configured , but after all , nothing really forbids an URI here too in principle ( by definition , the identifier is stable , which is what is really required ) . See for instance : " While this URL is generally hosted at the AS , the client instance can make no assumptions about its contents , composition , or relationship to the AS grant URL . " But there are security considerations too . We have many cases where we mix URI and URL in the same place ( ex 4.2.1 , title and text do n't match ) In general , URI matches better with the intent that the identifier may be reachable through various / generic means . Also RFC3986 is a mess and now quite old , but it does say that re specifications and related documentation should use the general term " URI " rather than the more restrictive terms " URL " and " URN " [ RFC3305 ] ( 1.1.3 ) . All that goes into the direction of using URI indeed . But in practice , most real cases probably will be using URLs in practice . Then explains quite well that " URI and IRI are just confusing " . URL wins the popularity contest , uri The only places where URLs are needed seem to be : in the subject identifiers , for DIDs ( in the related example ) . in 4.2.3.1 and 4.2.3.2 , for  encoded URLs with no padding ( + by the way , we should explain what we mean by no padding and URL safe ) in 7.1 , cert#S256 ( string ) is a URL in 7.1.1 , " a client publishing a public key at a URL " ( since we 're refering to a practical use case ) in 7.3.1 , http message signing refers to URLs in 7.3.3 , jws many places in the security considerations provide wisdom for real implementations , which do refer to URLs , and I would tend to think that makes more sense maybe a few other places that will be discovered when doing the change in a systematic way Therefore here is what I suggest : change all URL to URI , except in the cases mentioned just above if it helps , we could include an additional description in the elements , clarifying in one single that the various possibilities for URIs in our protocol , instead of repeating in multiple places . Knowing that most of our examples and security considerations are based on URLs . Let me know what you think , it 's in so many places ( also in section links ) that I prefer to check before ... 
 In the section “ Display of a Short User Code ” it says the URL MUST be stable so that the client can be statically configured with it . This seems to contradict the idea of returning the URL in the response here especially since the URL is n’t even required . Either the client is statically configured with a URL and so it does n’t need the URL in the response , or the client needs the URL in the response because it is not statically configured . It seems the MUST is too restrictive here . 
 The normative language might need to be tweaked here , but some background could help : This is based off of similar requirements in as this takes the place of the . Note that the equivalent of is just to use the interaction method , which allows us to avoid the security issues enumerated in that RFC around that function . 
 Proposal change set : create a three - tier interaction start method to handle different use cases with different dynamic portions : long arbitrary URL , suitable for QR code or browser redirect short arbitrary URL plus user code , suitable for things like set - top boxes that ca n't rely on QR codes on secondary devices and ca n't redirect user code alone , no URL included in the response ; URL the user is sent to is static ; suitable for limited interaction devices like voice - only interfaces that ca n't show a different URL at runtime This would probably change the name of the start mode , remove the from the start mode , and create a new kind of start mode that has both dynamic URL and user code in the response .
Paragraph (version A):
This document contains non-normative examples of partial and complete
HTTP messages, JSON structures, URLs, query components, keys, and
other elements.  Some examples use a single trailing backslash "\" to
indicate line wrapping for long values, as per RFC8792.  The "\"
character and leading spaces on wrapped lines are not part of the
value.
Paragraph (version B):
This document contains non-normative examples of partial and complete
HTTP messages, JSON structures, URIs, query components, keys, and
other elements.  Whenever possible, the document uses URI as a
generic term, since it aligns with RFC3986 recommendations and
matches better with the intent that the identifier may be reachable
through various/generic means (compared to URLs).  Some examples use
a single trailing backslash "\" to indicate line wrapping for long
values, as per RFC8792.  The "\" character and leading spaces on
wrapped lines are not part of the value.
Paragraph (version A):
end user/AS: when the client supports it (see response-interact),
the end user gets to interact with front-channel URLs provided by
the AS.  See security-front-channel for some considerations in
trusting these interactions.
Paragraph (version B):
end user/AS: when the client supports it (see response-interact),
the end user gets to interact with front-channel URIs provided by
the AS.  See security-front-channel for some considerations in
trusting these interactions.
Paragraph (version A):
In this example flow, the client instance is a web application that
wants access to resources on behalf of the current user, who acts as
both the end user and the resource owner (RO).  Since the client
instance 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 redirection URL used for interaction is a service hosted by the
AS in this example.  The client instance 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 B):
In this example flow, the client instance is a web application that
wants access to resources on behalf of the current user, who acts as
both the end user and the resource owner (RO).  Since the client
instance is capable of directing the user to an arbitrary URI and
receiving responses from the user's browser, interaction here is
handled through front-channel redirects using the user's browser.
The redirection URI used for interaction is a service hosted by the
AS in this example.  The client instance 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 client instance stores the verification and continuation
information from (3) in the session from (1).  The client instance
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 B):
The client instance stores the verification and continuation
information from (3) in the session from (1).  The client instance
then interaction-redirect given by the AS in (3).  The user's
browser loads the interaction redirect URI.  The AS loads the
pending request based on the incoming URI generated in (3).
Paragraph (version A):
When the AS is done interacting with the user, the AS interaction-
callback to the client instance using the redirect URL provided in
(2).  The redirect URL is augmented with an interaction reference
that the AS associates with the ongoing request created in (2) and
referenced in (4).  The redirect 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 end user never being returned to
the client instance and handle timeouts appropriately.
Paragraph (version B):
When the AS is done interacting with the user, the AS interaction-
callback to the client instance using the redirect URI provided in
(2).  The redirect URI is augmented with an interaction reference
that the AS associates with the ongoing request created in (2) and
referenced in (4).  The redirect URI 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 end user never being returned to
the client instance and handle timeouts appropriately.
Paragraph (version A):
In this example flow, the client instance 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 URL the user enters
the code at is an interactive service hosted by the AS in this
example.  The client instance 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 client instance 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 end user and RO,
though the user is not assumed to be interacting with the client
instance through the same web browser used for interaction at the AS.
Paragraph (version B):
In this example flow, the client instance 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 URI.  The URI the user enters
the code at is an interactive service hosted by the AS in this
example.  The client instance is not capable of presenting an
arbitrary URI to the user, nor is it capable of accepting incoming
HTTP requests from the user's browser.  The client instance 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 end user and RO,
though the user is not assumed to be interacting with the client
instance through the same web browser used for interaction at the AS.
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 client instance's documentation.  The AS also
includes information the client instance 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 B):
The AS determines that interaction is needed and response with a
response-interact-usercode.  This could optionally include a URI
to direct the user to, but this URI should be static and so could
be configured in the client instance's documentation.  The AS also
includes information the client instance 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 user's directs their browser to the user code URL.  This URL
is stable and can be communicated via the client software's
documentation, the AS documentation, or the client software
itself.  Since it is assumed that the RO will interact with the AS
through a secondary device, the client instance does not provide a
mechanism to launch the RO's browser at this URL.
Paragraph (version B):
The user's directs their browser to the user code URI.  This URI
is stable and can be communicated via the client software's
documentation, the AS documentation, or the client software
itself.  Since it is assumed that the RO will interact with the AS
through a secondary device, the client instance does not provide a
mechanism to launch the RO's browser at this URI.
Paragraph (version A):
In this example flow, the client instance receives an access token to
access a resource server through some valid GNAP process.  The client
instance uses that token at the RS for some time, but eventually the
access token expires.  The client instance then gets a new access
token by rotating the expired access token at the AS using the
token's management URL.
Paragraph (version B):
In this example flow, the client instance receives an access token to
access a resource server through some valid GNAP process.  The client
instance uses that token at the RS for some time, but eventually the
access token expires.  The client instance then gets a new access
token by rotating the expired access token at the AS using the
token's management URI.
Paragraph (version A):
Often, the AS will require authorization 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 end user by
facilitating the process through means such as redirection to a URL
or 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 concluded through a callback mechanism.
Paragraph (version B):
Often, the AS will require authorization 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 end user by
facilitating the process through means such as redirection to a URI
or 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 concluded through a callback mechanism.
Paragraph (version A):
In this non-normative example, the client instance is indicating that
it can request-interact-redirect the end user to an arbitrary URL and
can receive a request-interact-callback-redirect through a browser
request.
Paragraph (version B):
In this non-normative example, the client instance is indicating that
it can request-interact-redirect the end user to an arbitrary URI and
can receive a request-interact-callback-redirect through a browser
request.
Paragraph (version A):
The AS SHOULD handle any interact request as a one-time-use mechanism
and SHOULD apply suitable timeouts to any interaction mechanisms
provided, including user codes and redirection URLs.  The client
instance SHOULD apply suitable timeouts to any callback URLs.
Paragraph (version B):
The AS SHOULD handle any interact request as a one-time-use mechanism
and SHOULD apply suitable timeouts to any interaction mechanisms
provided, including user codes and redirection URIs.  The client
instance SHOULD apply suitable timeouts to any callback URIs.
Paragraph (version A):
If the client instance is capable of directing the end user to a URL
defined by the AS at runtime, the client instance indicates this by
including "redirect" in the array under the "start" key.  The means
by which the client instance will activate this URL is out of scope
of this specification, but common methods include an HTTP redirect,
launching a browser on the end user's device, providing a scannable
image encoding, and printing out a URL to an interactive console.
While this URL is generally hosted at the AS, the client instance can
make no assumptions about its contents, composition, or relationship
to the AS grant URL.
Paragraph (version B):
If the client instance is capable of directing the end user to a URI
defined by the AS at runtime, the client instance indicates this by
including "redirect" in the array under the "start" key.  The means
by which the client instance will activate this URI is out of scope
of this specification, but common methods include an HTTP redirect,
launching a browser on the end user's device, providing a scannable
image encoding, and printing out a URI to an interactive console.
While this URI is generally hosted at the AS, the client instance can
make no assumptions about its contents, composition, or relationship
to the AS grant URI.
Paragraph (version A):
If the client instance can open a URL associated with an application
on the end user's device, the client instance indicates this by
including "app" in the array under the "start" key.  The means by
which the client instance 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 client instance and
request, the AS returns an app interaction response with an app URL
payload response-interact-app.  The client instance manages this
interaction method as described in interaction-app.
Paragraph (version B):
If the client instance can open a URI associated with an application
on the end user's device, the client instance indicates this by
including "app" in the array under the "start" key.  The means by
which the client instance determines the application to open with
this URI are out of scope of this specification.
Paragraph (version B):
If this interaction mode is supported for this client instance and
request, the AS returns an app interaction response with an app URI
payload response-interact-app.  The client instance manages this
interaction method as described in interaction-app.
Paragraph (version A):
If the client instance is capable of displaying or otherwise
communicating a short, human-entered code to the RO, the client
instance indicates this by including "user_code" in the array under
the "start" key.  This code is to be entered at a static URL that
does not change at runtime.  While this URL is generally hosted at
the AS, the client instance can make no assumptions about its
contents, composition, or relationship to the AS grant URL.
Paragraph (version B):
If the client instance is capable of displaying or otherwise
communicating a short, human-entered code to the RO, the client
instance indicates this by including "user_code" in the array under
the "start" key.  This code is to be entered at a static URI that
does not change at runtime.  While this URI is generally hosted at
the AS, the client instance can make no assumptions about its
contents, composition, or relationship to the AS grant URI.
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 end user are the
same entity.  As such, the client instance MUST ensure the end user
is present on the request to prevent substitution attacks.
Paragraph (version B):
Since the incoming request to the callback URI is from the RO's
browser, this method is usually used when the RO and end user are the
same entity.  As such, the client instance MUST ensure the end user
is present on the request to prevent substitution attacks.
Paragraph (version A):
Since the incoming request to the callback URL is from the AS and not
from the RO's browser, the client instance MUST NOT require the end
user to be present on the incoming HTTP request.
Paragraph (version B):
Since the incoming request to the callback URI is from the AS and not
from the RO's browser, the client instance MUST NOT require the end
user to be present on the incoming HTTP request.
Paragraph (version A):
In this example, the AS is returning a bearer response-token-single
with a management URL and a response-subject in the form of an opaque
identifier.
Paragraph (version A):
In this example, the AS is returning set of response-subject,
simultaneously as an opaque identifier, an email address, and a
decentralized identifier (DID).
Paragraph (version B):
In this example, the AS is returning a bearer response-token-single
with a management URI and a response-subject in the form of an opaque
identifier.
Paragraph (version B):
In this example, the AS is returning set of response-subject,
simultaneously as an opaque identifier, an email address, and a
decentralized identifier URL (DID).
Paragraph (version A):
The following non-normative example shows a single access token bound
to the client instance's key used in the initial request, with a
management URL, and that has access to three described resources (one
using an object and two described by reference strings).
Paragraph (version B):
The following non-normative example shows a single access token bound
to the client instance's key used in the initial request, with a
management URI, and that has access to three described resources (one
using an object and two described by reference strings).
Paragraph (version A):
In this non-normative example, two tokens are issued under the names
"token1" and "token2", and only the first token has a management URL
associated with it.
Paragraph (version B):
In this non-normative example, two tokens are issued under the names
"token1" and "token2", and only the first token has a management URI
associated with it.
Paragraph (version A):
If the client instance indicates that it can request-interact-
redirect and the AS supports this mode for the client instance's
request, the AS responds with the "redirect" field, which is a string
containing the URL to direct the end user to.  This URL MUST be
unique for the request and MUST NOT contain any security-sensitive
information such as user identifiers or access tokens.
Paragraph (version A):
The client instance sends the end user to the URL to interact with
the AS.  The client instance MUST NOT alter the URL in any way.  The
means for the client instance to send the end user 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.  See details of
the interaction in interaction-redirect.
Paragraph (version A):
If the client instance indicates that it can request-interact-app and
the AS supports this mode for the client instance's request, the AS
responds with the "app" field, which is a string containing the URL
for the client instance to launch.  This URL MUST be unique for the
request and MUST NOT contain any security-sensitive information such
as user identifiers or access tokens.
Paragraph (version A):
The client instance launches the URL as appropriate on its platform,
and the means for the client instance to launch this URL is out of
scope of this specification.  The client instance MUST NOT alter the
URL in any way.  The client instance MAY attempt to detect if an
installed application will service the URL being sent before
attempting to launch the application URL.  See details of the
interaction in interaction-app.
Paragraph (version B):
If the client instance indicates that it can request-interact-
redirect and the AS supports this mode for the client instance's
request, the AS responds with the "redirect" field, which is a string
containing the URI to direct the end user to.  This URI MUST be
unique for the request and MUST NOT contain any security-sensitive
information such as user identifiers or access tokens.
Paragraph (version B):
The client instance sends the end user to the URI to interact with
the AS.  The client instance MUST NOT alter the URI in any way.  The
means for the client instance to send the end user to this URI 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 URI in an interactive console.  See details of
the interaction in interaction-redirect.
Paragraph (version B):
If the client instance indicates that it can request-interact-app and
the AS supports this mode for the client instance's request, the AS
responds with the "app" field, which is a string containing the URI
for the client instance to launch.  This URI MUST be unique for the
request and MUST NOT contain any security-sensitive information such
as user identifiers or access tokens.
Paragraph (version B):
The client instance launches the URI as appropriate on its platform,
and the means for the client instance to launch this URI is out of
scope of this specification.  The client instance MUST NOT alter the
URI in any way.  The client instance MAY attempt to detect if an
installed application will service the URI being sent before
attempting to launch the application URI.  See details of the
interaction in interaction-app.
Paragraph (version A):
The client instance SHOULD also communicate the URL if possible to
facilitate user interaction, but since the URL should be stable, the
client instance 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
client instance redirect the end user to the URL given here at
runtime.  Consequently, the URL needs to be stable enough that a
client instance could be statically configured with it, perhaps
referring the end user to the URL via documentation instead of
through an interactive means.  If the client instance is capable of
communicating an arbitrary URL to the end user, such as through a
scannable code, the client instance can use the request-interact-
redirect mode for this purpose instead of or in addition to the user
code mode.
Paragraph (version B):
The client instance SHOULD also communicate the URI if possible to
facilitate user interaction, but since the URI should be stable, the
client instance 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
client instance redirect the end user to the URI given here at
runtime.  Consequently, the URI needs to be stable enough that a
client instance could be statically configured with it, perhaps
referring the end user to the URI via documentation instead of
through an interactive means.  If the client instance is capable of
communicating an arbitrary URI to the end user, such as through a
scannable code, the client instance can use the request-interact-
redirect mode for this purpose instead of or in addition to the user
code mode.
Paragraph (version A):
When the interaction is completed, the interaction component MUST
contact the client instance using either a redirect or launch of the
RO's browser or through an HTTP POST to the client instance's
callback URL using the method indicated in the request-interact-
finish as described in interaction-finish.
Paragraph (version B):
When the interaction is completed, the interaction component MUST
contact the client instance using either a redirect or launch of the
RO's browser or through an HTTP POST to the client instance's
callback URI using the method indicated in the request-interact-
finish as described in interaction-finish.
Paragraph (version A):
In many cases, the URI indicates a web page hosted at the AS,
allowing the AS to authenticate the end user as the RO and
interactively provide consent.  If the URI is hosted by the AS, 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 client instance even if a
request-interact-callback-redirect.  If the URI is not hosted by the
AS directly, the means of communication between the AS and this URI
are out of scope for this specification.
Paragraph (version B):
In many cases, the URI indicates a web page hosted at the AS,
allowing the AS to authenticate the end user as the RO and
interactively provide consent.  If the URI is hosted by the AS, the
AS MUST determine the grant request being referenced from the URI
value itself.  If the URI 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 client instance even if a
request-interact-callback-redirect.  If the URI is not hosted by the
AS directly, the means of communication between the AS and this URI
are out of scope for this specification.
Paragraph (version A):
When the end user is directed to enter a short code through the
response-interact-usercode mode, the client instance communicates the
user code to the end user and directs the end user to enter that code
at an associated URI.  This mode is used when the client instance is
not able to facilitate launching an arbitrary URI.  The associated
URI could be statically configured with the client instance or
communicated in the response from the AS, but the client instance
communicates that URL to the end user.  As a consequence, these URIs
SHOULD be short.
Paragraph (version B):
When the end user is directed to enter a short code through the
response-interact-usercode mode, the client instance communicates the
user code to the end user and directs the end user to enter that code
at an associated URI.  This mode is used when the client instance is
not able to facilitate launching an arbitrary URI.  The associated
URI could be statically configured with the client instance or
communicated in the response from the AS, but the client instance
communicates that URI to the end user.  As a consequence, these URIs
SHOULD be short.
Paragraph (version A):
When the client instance is directed to launch an application through
the response-interact-app mode, the client launches the URL as
appropriate to the system, such as through a deep link or custom URI
scheme registered to a mobile application.  The means by which the AS
and the launched application communicate with each other and perform
any of the required actions are out of scope for this specification.
Paragraph (version B):
When the client instance is directed to launch an application through
the response-interact-app mode, the client launches the URI as
appropriate to the system, such as through a deep link or custom URI
scheme registered to a mobile application.  The means by which the AS
and the launched application communicate with each other and perform
any of the required actions are out of scope for this specification.
Paragraph (version A):
When using the response-interact-finish, the AS signals to the client
instance that interaction is complete and the request can be
continued by directing the RO (in their browser) back to the client
instance's redirect URL sent in request-interact-callback-redirect.
Paragraph (version A):
The AS secures this redirect by adding the hash and interaction
reference as query parameters to the client instance's redirect URL.
Paragraph (version A):
The means of directing the RO to this URL are outside the scope of
this specification, but common options include redirecting the RO
from a web page and launching the system browser with the target URL.
See security-redirect-status-codes for considerations on which HTTP
status code to use when redirecting a request that potentially
contains credentials.
Paragraph (version B):
When using the response-interact-finish, the AS signals to the client
instance that interaction is complete and the request can be
continued by directing the RO (in their browser) back to the client
instance's redirect URI sent in request-interact-callback-redirect.
Paragraph (version B):
The AS secures this redirect by adding the hash and interaction
reference as query parameters to the client instance's redirect URI.
Paragraph (version B):
The means of directing the RO to this URI are outside the scope of
this specification, but common options include redirecting the RO
from a web page and launching the system browser with the target URI.
See security-redirect-status-codes for considerations on which HTTP
status code to use when redirecting a request that potentially
contains credentials.
Paragraph (version A):
When using the response-interact-finish, the AS signals to the client
instance that interaction is complete and the request can be
continued by sending an HTTP POST request to the client instance's
callback URL sent in request-interact-callback-push.
Paragraph (version B):
When using the response-interact-finish, the AS signals to the client
instance that interaction is complete and the request can be
continued by sending an HTTP POST request to the client instance's
callback URI sent in request-interact-callback-push.
Paragraph (version A):
The "hash" parameter in the request to the client instance'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 client instance to protect itself against several kinds of
session fixation and injection attacks.  The AS MUST always provide
this hash, and the client instance MUST validate the hash when
received.
Paragraph (version B):
The "hash" parameter in the request to the client instance's callback
URI ties the front channel response to an ongoing request by using
values known only to the parties involved.  This security mechanism
allows the client instance to protect itself against several kinds of
session fixation and injection attacks.  The AS MUST always provide
this hash, and the client instance MUST validate the hash when
received.
Paragraph (version A):
The continuation access token is initially bound to the same key and
method the client instance used to make the initial request.  As a
consequence, when the client instance makes any calls to the
continuation URL, the client instance MUST present the continuation
access token as described in use-access-token and present proof of
the client instance's key (or its most recent rotation) by signing
the request as described in binding-keys.  The AS MUST validate all
keys presented by the client instance or referenced in an ongoing
request for each call within that request.
Paragraph (version B):
The continuation access token is initially bound to the same key and
method the client instance used to make the initial request.  As a
consequence, when the client instance makes any calls to the
continuation URI, the client instance MUST present the continuation
access token as described in use-access-token and present proof of
the client instance's key (or its most recent rotation) by signing
the request as described in binding-keys.  The AS MUST validate all
keys presented by the client instance or referenced in an ongoing
request for each call within that request.
Paragraph (version A):
The AS MUST be able to tell from the client instance's request which
specific ongoing request is being accessed, using a combination of
the continuation URL, the provided continuation access token, and the
client instance identified by the key signature.  If the AS cannot
determine a single active grant request to map the continuation
request to, the AS MUST return an error.
Paragraph (version B):
The AS MUST be able to tell from the client instance's request which
specific ongoing request is being accessed, using a combination of
the continuation URI, the provided continuation access token, and the
client instance identified by the key signature.  If the AS cannot
determine a single active grant request to map the continuation
request to, the AS MUST return an error.
Paragraph (version A):
If an access token response includes the "manage" parameter as
described in response-token-single, the client instance MAY call this
URL to manage the access token with any of the actions defined in the
following sections: rotate and revoke.  Other actions are undefined
by this specification.
Paragraph (version B):
If an access token response includes the "manage" parameter as
described in response-token-single, the client instance MAY call this
URI to manage the access token with any of the actions defined in the
following sections: rotate and revoke.  Other actions are undefined
by this specification.
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 client
instance, and that the presented key is appropriate to the token.
Paragraph (version B):
The AS validates that the token presented is associated with the
management URI, that the AS issued the token to the given client
instance, and that the presented key is appropriate to the token.
Paragraph (version A):
If the token is validated and the key is appropriate for the request,
the AS MUST invalidate the current access token associated with this
URL, if possible.  Note that stateless access tokens can make
proactive revocation difficult within a system, see security-
stateless-tokens.
Paragraph (version B):
If the token is validated and the key is appropriate for the request,
the AS MUST invalidate the current access token associated with this
URI, if possible.  Note that stateless access tokens can make
proactive revocation difficult within a system, see security-
stateless-tokens.
Paragraph (version A):
The AS responds with an HTTP 200 with a JSON body consisting of the
rotated access token in the "access_token" field described in
response-token-single.  The value of the access token MUST NOT be the
same as the current value of the access token used to access the
management API.  The response MUST include an access token management
URL, and the value of this URL MAY be different from the URL used by
the client instance to make the rotation call.  The client instance
MUST use this new URL to manage the rotated access token.
Paragraph (version B):
The AS responds with an HTTP 200 with a JSON body consisting of the
rotated access token in the "access_token" field described in
response-token-single.  The value of the access token MUST NOT be the
same as the current value of the access token used to access the
management API.  The response MUST include an access token management
URI, and the value of this URI MAY be different from the URI used by
the client instance to make the rotation call.  The client instance
MUST use this new URI to manage the rotated access token.
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 client
instance'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 B):
Though the AS MAY revoke an access token at any time for any reason,
the token management function is specifically for the client
instance'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 URI as valid, since the end result is
still the token not being usable.
Paragraph (version A):
The means of dereferencing this value are out of scope for this
specification.  Commonly, key references are created by the AS and
are not necessarily needed to be dereferencable by the client.  These
types of key references are an internal reference to the AS, such as
an identifier of a record in a database.  In other applications, it
can be useful to use key references that are resolvable by both
clients and ASs, which could be accomplished by e.g. a client
publishing a public key at a URL.  For interoperability, this method
could later be described as an extension.
Paragraph (version B):
The means of dereferencing this value are out of scope for this
specification.  Commonly, key references are created by the AS and
are not necessarily needed to be dereferencable by the client.  These
types of key references are an internal reference to the AS, such as
an identifier of a record in a database.  In other applications, it
can be useful to use key references that are resolvable by both
clients and ASs, which could be accomplished by e.g. a client
publishing a public key at a URI.  For interoperability, this method
could later be described as an extension.
Paragraph (version A):
For example, if a specific user is claimed to be present prior to
interaction, but a different user is shown to be present during
interaction, the AS can either determine this to be an error or
signal to the client instance through returned subject information
that the current user has changed from what the client instance
thought.  This user information can also be used by the AS to
streamline the interaction process when the user is present.  For
example, instead of having the user type in their account identifier
during interaction at a redirected URL, the AS can immediately
challenge the user for their account credentials.  Alternatively, if
an existing session is detected, the AS can determine that it matches
the identifier provided by the client and subsequently skip an
explicit authentication event by the resource owner.
Paragraph (version B):
For example, if a specific user is claimed to be present prior to
interaction, but a different user is shown to be present during
interaction, the AS can either determine this to be an error or
signal to the client instance through returned subject information
that the current user has changed from what the client instance
thought.  This user information can also be used by the AS to
streamline the interaction process when the user is present.  For
example, instead of having the user type in their account identifier
during interaction at a redirected URI, the AS can immediately
challenge the user for their account credentials.  Alternatively, if
an existing session is detected, the AS can determine that it matches
the identifier provided by the client and subsequently skip an
explicit authentication event by the resource owner.
Paragraph (version A):
Most information passed through the web-browser is susceptible to
interception and possible manipulation by elements within the browser
such as scripts loaded within pages.  Information in the URL is
exposed through browser and server logs, and can also leak to other
parties through HTTP "Referer" headers.
Paragraph (version A):
GNAP's design limits the information passed directly through the
browser, allowing for opaque URLs in most circumstances.  For the
redirect-based interaction finish mechanism, named query parameters
are used to carry unguessable opaque values.  For these, GNAP
requires creation and validation of a cryptographic hash to protect
the query parameters added to the URL and associate them with an
ongoing grant process.  The client instance has to properly validate
this hash to prevent an attacker from injecting an interaction
reference intended for a different AS or client instance.
Paragraph (version A):
Several interaction start mechanisms use URLs created by the AS and
passed to the client instance.  While these URLs are opaque to the
client instance, it's possible for the AS to include parameters,
paths, and other pieces of information that could leak security data
or be manipulated by a party in the middle of the transaction.
Paragraph (version A):
The callback URL used in interaction finish mechanisms is defined by
the client instance.  This URL is opaque to the AS, but can contain
information relevant to the client instance's operations.  In
particular, the client instance can include state information to
allow the callback request to be associated with an ongoing grant
request.
Paragraph (version A):
Since this URL is exposed to the end user's browser, it is
susceptible to both logging and manipulation in transit before the
request is made to the client software.  As such, a client instance
should never put security-critical or private information into the
callback URL in a cleartext form.  For example, if the client
software includes a post-redirect target URL in its callback URL to
the AS, this target URL could be manipulated by an attacker, creating
an open redirector at the client.  Instead, a client instance can use
an unguessable identifier into the URL that can then be used by the
client software to look up the details of the pending request.  Since
this approach requires some form of statefulness by the client
software during the redirection process, clients that are not capable
of holding state through a redirect should not use redirect-based
interaction mechanisms.
Paragraph (version B):
Most information passed through the web-browser is susceptible to
interception and possible manipulation by elements within the browser
such as scripts loaded within pages.  Information in the URI is
exposed through browser and server logs, and can also leak to other
parties through HTTP "Referer" headers.
Paragraph (version B):
GNAP's design limits the information passed directly through the
browser, allowing for opaque URIs in most circumstances.  For the
redirect-based interaction finish mechanism, named query parameters
are used to carry unguessable opaque values.  For these, GNAP
requires creation and validation of a cryptographic hash to protect
the query parameters added to the URI and associate them with an
ongoing grant process.  The client instance has to properly validate
this hash to prevent an attacker from injecting an interaction
reference intended for a different AS or client instance.
Paragraph (version B):
Several interaction start mechanisms use URIs created by the AS and
passed to the client instance.  While these URIs are opaque to the
client instance, it's possible for the AS to include parameters,
paths, and other pieces of information that could leak security data
or be manipulated by a party in the middle of the transaction.
Paragraph (version B):
The callback URI used in interaction finish mechanisms is defined by
the client instance.  This URI is opaque to the AS, but can contain
information relevant to the client instance's operations.  In
particular, the client instance can include state information to
allow the callback request to be associated with an ongoing grant
request.
Paragraph (version B):
Since this URI is exposed to the end user's browser, it is
susceptible to both logging and manipulation in transit before the
request is made to the client software.  As such, a client instance
should never put security-critical or private information into the
callback URI in a cleartext form.  For example, if the client
software includes a post-redirect target URI in its callback URI to
the AS, this target URI could be manipulated by an attacker, creating
an open redirector at the client.  Instead, a client instance can use
an unguessable identifier into the URI that can then be used by the
client software to look up the details of the pending request.  Since
this approach requires some form of statefulness by the client
software during the redirection process, clients that are not capable
of holding state through a redirect should not use redirect-based
interaction mechanisms.
Paragraph (version A):
Redirection away from the initial URL in an interaction session could
also leak information found in that initial URL through the HTTP
"Referer" header field, which would be sent by the user agent to the
redirect target.  To avoid such leakage, a server can first redirect
to an internal interstitial page without any identifying or sensitive
information on the URL before processing the request.  When the user
agent is ultimately redirected from this page, no part of the
original interaction URL will be found in the Referrer header.
Paragraph (version B):
Redirection away from the initial URI in an interaction session could
also leak information found in that initial URI through the HTTP
"Referer" header field, which would be sent by the user agent to the
redirect target.  To avoid such leakage, a server can first redirect
to an internal interstitial page without any identifying or sensitive
information on the URI before processing the request.  When the user
agent is ultimately redirected from this page, no part of the
original interaction URI will be found in the Referrer header.
Paragraph (version A):
Note that in GNAP, the client instance has to choose its interaction
finish URL prior to making the first call to the AS.  As such, the
interaction finish URL will often have a unique identifier for the
ongoing request, allowing the client instance to access the correct
portion of its storage.  Since this URL is passed to other parties
and often used through a browser, this URL should not contain any
security-sensitive information that would be valuable to an attacker,
such as any token identifier, nonce, or user information.  Instead, a
cryptographically random value is suggested.
Paragraph (version B):
Note that in GNAP, the client instance has to choose its interaction
finish URI prior to making the first call to the AS.  As such, the
interaction finish URI will often have a unique identifier for the
ongoing request, allowing the client instance to access the correct
portion of its storage.  Since this URI is passed to other parties
and often used through a browser, this URI should not contain any
security-sensitive information that would be valuable to an attacker,
such as any token identifier, nonce, or user information.  Instead, a
cryptographically random value is suggested.
Paragraph (version A):
Several parts of the GNAP process make use of unguessable randomized
values, such as nonces, tokens, and randomized URLs.  Since these
values are intended to be unique, a sufficiently powerful attacker
could make a large number of requests to trigger generation of
randomized values in an attempt to exhaust the random number
generation space.  While this attack is particularly applicable to
the AS, client software could likewise be targeted by an attacker
triggering new grant requests against an AS.
Paragraph (version B):
Several parts of the GNAP process make use of unguessable randomized
values, such as nonces, tokens, and randomized URIs.  Since these
values are intended to be unique, a sufficiently powerful attacker
could make a large number of requests to trigger generation of
randomized values in an attempt to exhaust the random number
generation space.  While this attack is particularly applicable to
the AS, client software could likewise be targeted by an attacker
triggering new grant requests against an AS.
Paragraph (version A):
Some interaction methods in GNAP make use of URLs accessed through
the end user's browser, known collectively as front-channel
communication.  These URLs are most notably present in the "redirect"
interaction "start" method and the "redirect" interaction "finish"
mode.  Since these URLs are intended to be given to the end user, the
end user and their browser will be subjected to anything hosted at
that URL including viruses, malware, and phishing scams.  This kind
of risk is inherent to all redirection-based protocols, including
GNAP when used in this way.
Paragraph (version A):
When talking to a new or unknown AS, a client instance might want to
check the URL from the interaction "start" against a blocklist and
warn the end user before redirecting them.  Many client instances
will provide an interstitial message prior to redirection in order to
prepare the user for control of the user experience being handed to
the domain of the AS, and such a method could be used to warn the
user of potential threats.  For instance, a rogue AS impersonating a
well-known service provider.  Client software can also prevent this
by managing an allowlist of known and trusted AS's.
Paragraph (version B):
Some interaction methods in GNAP make use of URIs accessed through
the end user's browser, known collectively as front-channel
communication.  These URIs are most notably present in the "redirect"
interaction "start" method and the "redirect" interaction "finish"
mode.  Since these URIs are intended to be given to the end user, the
end user and their browser will be subjected to anything hosted at
that URI including viruses, malware, and phishing scams.  This kind
of risk is inherent to all redirection-based protocols, including
GNAP when used in this way.
Paragraph (version B):
When talking to a new or unknown AS, a client instance might want to
check the URI from the interaction "start" against a blocklist and
warn the end user before redirecting them.  Many client instances
will provide an interstitial message prior to redirection in order to
prepare the user for control of the user experience being handed to
the domain of the AS, and such a method could be used to warn the
user of potential threats.  For instance, a rogue AS impersonating a
well-known service provider.  Client software can also prevent this
by managing an allowlist of known and trusted AS's.
Paragraph (version A):
Alternatively, an attacker could start a GNAP request with a known
and trusted AS but include their own attack site URL as the callback
for the redirect "finish" method.  The attacker would then send the
interaction "start" URL to the victim and get them to click on it.
Since the URL is at the known AS, the victim is inclined to do so.
The victim will then be prompted to approve the attacker's
application, and in most circumstances the victim will then be
redirected to the attacker's site whether or not the user approved
the request.  The AS could mitigate this partially by using a
blocklist and allowlist of interaction "finish" URLs during the
client instance's initial request, but this approach can be
especially difficult if the URL has any dynamic portion chosen by the
client software.  The AS can couple these checks with policies
associated with the client instance that has been authenticated in
the request.  If the AS has any doubt about the interaction finish
URL, the AS can provide an interstitial warning to the end user
before processing the redirect.
Paragraph (version A):
Ultimately, all protocols that use redirect-based communication
through the user's browser are susceptible to having an attacker try
to co-opt one or more of those URLs in order to harm the user.  It is
the responsibility of the AS and the client software to provide
appropriate warnings, education, and mitigation to protect end users.
Paragraph (version B):
Alternatively, an attacker could start a GNAP request with a known
and trusted AS but include their own attack site URI as the callback
for the redirect "finish" method.  The attacker would then send the
interaction "start" URI to the victim and get them to click on it.
Since the URI is at the known AS, the victim is inclined to do so.
The victim will then be prompted to approve the attacker's
application, and in most circumstances the victim will then be
redirected to the attacker's site whether or not the user approved
the request.  The AS could mitigate this partially by using a
blocklist and allowlist of interaction "finish" URIs during the
client instance's initial request, but this approach can be
especially difficult if the URI has any dynamic portion chosen by the
client software.  The AS can couple these checks with policies
associated with the client instance that has been authenticated in
the request.  If the AS has any doubt about the interaction finish
URI, the AS can provide an interstitial warning to the end user
before processing the redirect.
Paragraph (version B):
Ultimately, all protocols that use redirect-based communication
through the user's browser are susceptible to having an attacker try
to co-opt one or more of those URIs in order to harm the user.  It is
the responsibility of the AS and the client software to provide
appropriate warnings, education, and mitigation to protect end users.
Paragraph (version A):
There are several places within GNAP where a URL can be given to a
party causing it to fetch that URL during normal operation of the
protocol.  If an attacker is able to control the value of one of
these URLs within the protocol, the attacker could cause the target
system to execute a request on a URL that is within reach of the
target system but normally unavailable to the attacker.  For example,
an attacker sending a URL of "http://localhost/admin" to cause the
server to access an internal function on itself, or
"https://192.168.0.14/" to call a service behind a firewall.  Even if
the attacker does not gain access to the results of the call, the
side effects of such requests coming from a trusted host can be
problematic to the security and sanctity of such otherwise unexposed
endpoints.
Paragraph (version B):
There are several places within GNAP where a URI can be given to a
party causing it to fetch that URI during normal operation of the
protocol.  If an attacker is able to control the value of one of
these URIs within the protocol, the attacker could cause the target
system to execute a request on a URI that is within reach of the
target system but normally unavailable to the attacker.  For example,
an attacker sending a URL of "http://localhost/admin" to cause the
server to access an internal function on itself, or
"https://192.168.0.14/" to call a service behind a firewall.  Even if
the attacker does not gain access to the results of the call, the
side effects of such requests coming from a trusted host can be
problematic to the security and sanctity of such otherwise unexposed
endpoints.
Paragraph (version A):
In GNAP, the most vulnerable place in the core protocol is the
interaction-pushback, as the client instance is less trusted than the
AS and can use this method to make the AS call an arbitrary URL.
While it is not required by the protocol, the AS can fetch other
client-instance provided URLs such as the logo image or home page,
for verification or privacy-preserving purposes before displaying
them to the resource owner as part of a consent screen.  Furthermore,
extensions to GNAP that allow or require URL fetch could also be
similarly susceptible, such as a system for having the AS fetch a
client instance's keys from a presented URL instead of the client
instance presenting the key by value.  Such extensions are outside
the scope of this specification, but any system deploying such an
extension would need to be aware of this issue.
Paragraph (version A):
To help mitigate this problem, similar approaches to protecting
parties against security-front-channel can be used.  For example, all
URLs that can result in a direct request being made by a party in the
protocol can be filtered through an allowlist or blocklist.  For
example, an AS that supports the "push" based interaction "finish"
can compare the callback URL in the interaction request to a known
URL for a pre-registered client instance, or it can ensure that the
URL is not on a blocklist of sensitive URLs such as internal network
addresses.  However, note that because these types of calls happen
outside of the view of human interaction, it is not usually feasible
to provide notification and warning to someone before the request
needs to be executed, as is the case with redirection URLs.  As such,
SSRF is somewhat more difficult to manage at runtime, and systems
should generally refuse to fetch a URL if unsure.
Paragraph (version B):
In GNAP, the most vulnerable place in the core protocol is the
interaction-pushback, as the client instance is less trusted than the
AS and can use this method to make the AS call an arbitrary URI.
While it is not required by the protocol, the AS can fetch other
client-instance provided URIs such as the logo image or home page,
for verification or privacy-preserving purposes before displaying
them to the resource owner as part of a consent screen.  Furthermore,
extensions to GNAP that allow or require URI fetch could also be
similarly susceptible, such as a system for having the AS fetch a
client instance's keys from a presented URI instead of the client
instance presenting the key by value.  Such extensions are outside
the scope of this specification, but any system deploying such an
extension would need to be aware of this issue.
Paragraph (version B):
To help mitigate this problem, similar approaches to protecting
parties against security-front-channel can be used.  For example, all
URIs that can result in a direct request being made by a party in the
protocol can be filtered through an allowlist or blocklist.  For
example, an AS that supports the "push" based interaction "finish"
can compare the callback URI in the interaction request to a known
URI for a pre-registered client instance, or it can ensure that the
URI is not on a blocklist of sensitive URLs such as internal network
addresses.  However, note that because these types of calls happen
outside of the view of human interaction, it is not usually feasible
to provide notification and warning to someone before the request
needs to be executed, as is the case with redirection URLs.  As such,
SSRF is somewhat more difficult to manage at runtime, and systems
should generally refuse to fetch a URI if unsure.