Draft: draft-ietf-gnap-core-protocol

Commentary: This rewrite changes the framing of the " interaction " sections to showcase that the interactions themselves do n't have to take place through web pages hosted at the AS . The AS in fact has a wide variety of methods that it can use , with interaction ( web based or otherwise ) being among the most common and flexible . The AS could also use elements like digital wallets , shared secure storage , messaging fabrice , or bound assertions to communicate . Furthermore , the AS itself could be deployed in a variety of ways , with the interactive components being separate from the core delegation functions of the AS . 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-242 - -gnap - core - protocol - editors- 
 I agree with the intent but I think the starting point of the first two sequences could be improved if we were consistent in having  ( 1 ) always be Client Instance --- Request Access ---AS . If anything that happens before  ( 1 ) is in scope for GNAP , it would be useful to state that clearly up - front . If it 's a difference between GNAP Core and Extensions , then that could be stated up - front as well . 
 so changing diagram 1.4.1 ? ( removing 1 ) 
 changing that diagram will be the addressed in the PR targeted at fixing ( this has n't been done / pushed yet ) Remember , each PR is n't aiming at perfect , just " better " :) 
 The " user interaction " section of GNAP has always been intended to allow for many different kinds of practices , including things like discussed in The current writing makes it seem limited to just the RO interacting directly with the AS , and then only specified through a web browser . The section needs to be rewritten to take into account the variety of different acts that the AS can allow during negotiation process that results in the delegation to the client instance . See also 
 For the RFC to be self - contained , please add a section to the Introduction ( or an appendix ) summarizing the main changes from OAuth2 / OIDC , and the rationale for each delta . ( Originally raised by 
 Suggest to put this area in the wiki to have a deeper explanation 
 I 've started a wiki page with some content I had written up for another publication : 
 This information is important to the draft 's readership , and people are not seeing it ( e.g. ,  's mail from March 26 ) . Can we include it as - is in an appendix to the draft ? 
 I will submit a PR as an appendix . Note also that the editors prepared a short paper " Managing authorization grants beyond OAuth 2 " that has been accepted at . It was a nice way to get some external reviews . Will be published in 
 Resource Servers :  's note : This section is for discussion of possible advanced functionality . It seems like it should be a separate document or set of documents , and it 's not even close to being well - baked . This also adds additional endpoints to the AS , as this is separate from the token request process , and therefore would require RS - facing discovery or configuration information to make it work . Also - also , it does presume the RS can sign requests in the same way that a client does , but hopefully we can be more consistent with this than  was able to do . 
 Section 10 mentions : Calling back the AS , allows the AS to know to the existence of the RS . There are cases where the AS should be prevented to know which the RS is . When doing " Token Introspection " ( Section 10.1 ) , the AS may communicate to the RS some privileges without the client ( and hence the end - user ) knowing it ( and thus without the end - user consent ) . " Deriving a downstream token " ( Section 10.2 ) is described to allow a RS to act as a client instance and request a derived access token for a secondary RS . This can be done without a recall to the AS , if the name of the service to which the first RS belongs to is included into the access token . See the issue which contains more details on how to do it . " Registering a Resource Handle " ( Section 10.3 . ) allows the AS to know which RSs are trusting it . This should be avoided for RSs as soon as there is no bi - lateral trust relationships with the AS . This should also be avoided to allow large scale developments . A RS trusts some ASs to some extent , but the ASs do not necesarilly need to know which RSs are trusting them . Requesting Resources With Insufficient Access ( Section 10.4 ) is addressed in another issue . See " Requesting resources with insufficient access " The whole section would need to be re - written . 
 Section 10 is made of optional elements . Token introspection is not required , you could alternatively use a self - contained token . Deriving a token without the AS 's involvement is deeply problematic for most use cases as the AS is the root of trust in the system and overriding that would subvert the security model . Yes , introducing the RS to the AS lets the AS know about the RS as this is the point . 
 ( Section 10.4 ) Requesting Resources With Insufficient Access is NOT an optional element . Nevertheless , it is addressed in another issue . See " Requesting resources with insufficient access " . At the moment the text states : The phrasing of section 10 should be reworded to indicate that the sub - sections 1 , 2 & 3 describe optional functions . You also wrote : " introducing the RS to the AS lets the AS know about the RS as this is the point " . I do understand that this is necessary for some use cases , but not for all use cases , in particular when ACLs are used by the RS instead of capabilities 
 This section will be pulled out into a separate document , to be discussed by the working group . Note that in the future it could be re - incorporated into the core if the working group decides to restructure things that way . 
 Redirection to an arbitrary URL : Editor 's note : distinct from the URL the RC uses to request access , allowing an AS to separate its user - interactive functionality from its back - end security functionality . This is one aspect where the AS might actually be two separate roles . Namely , a delegation server ( back end ) and interaction server ( user - facing ) . Display of a Short User Code : Editor 's note : This is one aspect where the AS might actually be two separate roles . Namely , a delegation server ( back end ) and interaction server ( user - facing ) . 
 I believe this has been addressed by .
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 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 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 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 client instance will need to
response-continue in (8).  The AS associates this continuation
information with an ongoing request that will be referenced in
(4), (6), and (8).
Paragraph (version B):
The AS determines that interaction is needed and response with a
response-interact-redirect and response-interact-finish in (7).
The AS also includes information the client instance will need to
response-continue in (8).  The AS associates this continuation
information with an ongoing request that will be referenced in
(4), (6), and (8).
Paragraph (version 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 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 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 A):
In this scenario, the client instance does not call an RS and does
not request an access token.  Instead, the client instance only
requests and is returned response-subject.  Many different
interaction modes can be used in this scenario, so these are shown
only in the abstract here.
Paragraph (version A):
The client instance facilitates user-interaction as directed in
(2).
Paragraph (version B):
In this scenario, the client instance does not call an RS and does
not request an access token.  Instead, the client instance only
requests and is returned response-subject.  Many different
interaction modes can be used in this scenario, so these are shown
only in the abstract as functions of the AS here.
Paragraph (version B):
The client instance facilitates authorization as directed in (2).
Paragraph (version A):
Describes the client instance that is making this request,
including the key that the client instance will use to protect
this request and any continuation requests at the AS and any user-
facing information about the client instance used in interactions
at the AS.
Paragraph (version B):
Describes the client instance that is making this request,
including the key that the client instance will use to protect
this request and any continuation requests at the AS and any user-
facing information about the client instance used in interactions.
Paragraph (version A):
The AS can determine the RO's identity and permission for releasing
this information through user-interaction, AS policies, or request-
user.  If this is determined positively, the AS MAY response-subject
as requested.
Paragraph (version B):
The AS can determine the RO's identity and permission for releasing
this information through authorization, AS policies, or request-user.
If this is determined positively, the AS MAY response-subject as
requested.
Paragraph (version A):
Many times, the AS will require interaction with the RO in order to
approve a requested delegation to the client instance for both access
to resources and direct subject information.  Many times the end-user
using the client instance is the same person as the RO, and the
client instance can directly drive interaction with the AS by
redirecting the end-user on the same device, or by launching an
application.  Other times, the client instance can provide
information to start the RO's interaction on a secondary device, or
the client instance will wait for the RO to approve the request
asynchronously.  The client instance could also be signaled that
interaction has completed by the AS making callbacks.  To facilitate
all of these modes, the client instance declares the means that it
can interact using the "interact" field.
Paragraph (version B):
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):
The client instance declares the parameters for interaction methods
that it can support using the "interact" field.
Paragraph (version A):
Indicates that the client instance can direct the end-user to an
arbitrary URL at the AS for interaction.
Paragraph (version A):
Indicates that the client instance can communicate a human-
readable short code to the end-user for use with a stable URL at
the AS.
Paragraph (version A):
Indicates that the client instance can receive a redirect from the
end-user's device after interaction with the RO has concluded.
Paragraph (version A):
Indicates that the client instance can receive an HTTP POST
request from the AS after interaction with the RO has concluded.
Paragraph (version B):
Indicates that the client instance can direct the end-user to an
arbitrary URL for interaction.
Paragraph (version B):
Indicates that the client instance can communicate a human-
readable short code to the end-user for use with a stable URL.
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
sending the "redirect" field with the boolean value "true".  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.
Paragraph (version A):
If this interaction mode is supported for this client instance and
request, the AS returns a redirect interaction response response-
interact-redirect.
Paragraph (version B):
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
sending the "redirect" field with the boolean value "true".  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 this interaction mode is supported for this client instance and
request, the AS returns a redirect interaction response response-
interact-redirect.  The client instance manages this interaction
method as described in interaction-redirect.
Paragraph (version A):
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.
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 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 client instance and
request, the AS returns a user code and interaction URL as specified
in interaction-usercode.
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 URL
payload response-interact-app.  The client instance manages this
interaction method as described in interaction-app.
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 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.  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 A):
REQUIRED.  The callback method that the AS will use to contact the
client instance.  Valid values include "redirect" request-
interact-callback-redirect and "push" request-interact-callback-
push, with other values defined by IANA.
Paragraph (version B):
Indicates that the client instance can receive a redirect from
the end-user's device after interaction with the RO has
concluded.
Paragraph (version B):
Indicates that the client instance can receive an HTTP POST
request from the AS after interaction with the RO has
concluded.
Paragraph (version A):
If this interaction mode is supported for this client instance 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 B):
If this interaction mode is supported for this client instance and
request, the AS returns a nonce for use in validating response-
interact-finish.  Requests to the callback URI MUST be processed as
described in interaction-finish, and the AS MUST require presentation
of an interaction callback reference as described in continue-after-
interaction.
Paragraph (version A):
In this example, the AS is returning an response-interact-redirect, a
response-interact-callback, and a response-continue.
Paragraph (version B):
In this example, the AS is returning an response-interact-redirect, a
response-interact-finish, and a response-continue.
Paragraph (version 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.
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 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.
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
to direct the end-user to.  This URL MUST be unique for the request
and MUST NOT contain any security-sensitive information.
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.
Paragraph (version A):
If the client instance indicates that it can finish-interaction-modes
and the AS supports this mode for the client instance's request, the
AS responds with a "finish" field containing a nonce that the client
instance will use in validating the callback as defined in
interaction-finalize.
Paragraph (version A):
When the RO completes interaction at the AS, the AS MUST either
redirect the RO's browser or send an HTTP POST to the client
instance's callback URL using the method indicated in the finish-
interaction-modes as described in interaction-finalize.
Paragraph (version A):
If the AS returns a nonce, the client instance MUST NOT continue a
grant request before it receives the associated interaction reference
on the callback URI.
Paragraph (version B):
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 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 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 B):
The means for the launched application to communicate with the AS are
out of scope for this specification.
Paragraph (version B):
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 A):
RECOMMENDED.  The interaction URL that the client instance will
direct the RO to.  This URL MUST be stable at the AS such that
client instance's can be statically configured with it.
Paragraph (version A):
The client instance MUST communicate the "code" to the end-user 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 client instance.  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 B):
RECOMMENDED.  The interaction URL that the client instance will
direct the RO to.  This URL MUST be stable such that client
instances can be statically configured with it.
Paragraph (version B):
The client instance MUST communicate the "code" to the end-user in
some fashion, such as displaying it on a screen or reading it out
audibly.
Paragraph (version B):
See details of the interaction in interaction-usercode.
Paragraph (version B):
If the client instance indicates that it can request-interact-finish
and the AS supports this mode for the client instance's request, the
AS responds with a "finish" field containing a nonce that the client
instance will use in validating the callback as defined in
interaction-finish.
Paragraph (version 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 URL using the method indicated in the request-interact-
finish as described in interaction-finish.
Paragraph (version B):
If the AS returns a nonce, the client instance MUST NOT continue a
grant request before it receives the associated interaction reference
on the callback URI.  See details in interaction-finish.
Paragraph (version A):
The AS MUST return the "subject" field only in cases where the AS is
sure that the RO and the end-user are the same party.  This can be
accomplished through some forms of user-interaction.
Paragraph (version B):
The AS MUST return the "subject" field only in cases where the AS is
sure that the RO and the end-user are the same party.  This can be
accomplished through some forms of authorization.
Paragraph (version A):
If the client instance request-interact, and the AS determines that
interaction is required and responds to one or more of the client
instance's interaction modes, the client instance 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 client instance 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 client instance even
if a request-interact-callback-redirect.
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
client instance 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
end-user, since the client instance has to communicate the
redirection URI to the end-user.
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 client instance even
if a request-interact-callback-redirect.
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
client instance 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 end-user,
since the client instance has to communicate the user code to
someone, there are cases where the end-user and RO are separate
parties and the authorization happens asynchronously.
Paragraph (version A):
When the client instance 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
client instance to continue.  If this mode is not available, the AS
SHOULD instruct the RO to return to their client instance 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 client instance 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 create an interaction reference and associate that
reference with the current interaction and the underlying pending
request.  This value MUST be sufficiently random so as not to be
guessable by an attacker.  The interaction reference MUST be one-
time-use.
Paragraph (version A):
The AS MUST calculate a hash value based on the client instance and
AS nonces and the interaction reference, as described in interaction-
hash.  The client instance will use this value to validate the return
call from the AS.
Paragraph (version A):
The AS then MUST send the hash and interaction reference based on the
interaction finalization mode as described in the following sections.
Paragraph (version A):
When using the response-interact-callback, 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 B):
The AS determines what authorizations and consents are required to
fulfill this requested delegation.  The details of how the AS makes
this determination are out of scope for this document.  However,
there are several common patterns defined and supported by GNAP for
fulfilling these requirements, including information sent by the
client instance, information gathered through the interaction
process, and information supplied by external parties.  An individual
AS can define its own policies and processes for deciding when and
how to gather the necessary authorizations and consent.
Paragraph (version B):
The AS will verify this presented information in the context of the
client instance's request and can only trust the information as much
as it trusts the presentation and context of the information.  If the
AS determines that the information presented in the initial request
is sufficient for granting the requested access, the AS MAY return
the positive results immediately in its response with access tokens
and subject information.
Paragraph (version B):
The AS is also allowed to request authorization from more than one
RO, if the AS deems fit.  For example, a medical record might need to
be released by both an attending nurse and a physician, or both
owners of a bank account need to sign off on a transfer request.
Alternatively, the AS could require N of M possible RO's to approve a
given request in order.  The AS could also determine that the end
user is not the appropriate RO for a given request and reach out to
the appropriate RO asynchronously.  The details of determining which
RO's are required for a given request are out of scope for this
specification.
Paragraph (version B):
The client instance can also indicate that it is capable of
facilitating interaction with the end user, another party, or another
piece of software through its request-interact-start request.  In
many cases, the end user is delegating their own access as RO to the
client instance.  Here, the AS needs to determine the identity of the
end user and will often need to interact directly with the end user
to determine their status as an RO and collect their consent.  If the
AS has determined that authorization is required and the AS can
support one or more of the requested interaction start methods, the
AS returns the associated response-interact.  The client instance
SHOULD interaction-start in order to facilitate the granting of the
request.  If more than one interaction start method is available, the
means by which the client chooses which methods to follow is out of
scope of this specification.  The client instance MUST use each
interaction method once at most.
Paragraph (version B):
After starting interaction, the client instance can then make a
continue-request either in response to a signal indicating the
interaction-finish, through polling, or through some other method
defined by an extension of this specification.
Paragraph (version B):
If the AS and client instance have not reached a state where the
delegation can be granted, the AS and client instance can repeat the
interaction process as long as the AS supplies the client instance
with response-continue to facilitate the ongoing requests.
Paragraph (version B):
To initiate an interaction start method indicated by the response-
interact from the AS, the client instance follows the steps defined
by that interaction method.  The actions of the client instance
required for the interaction start modes defined in this
specification are described in the following sections.
Paragraph (version B):
When the end user is directed to an arbitrary URI through the
response-interact-redirect mode, the client instance facilitates
opening the URI through the end user's web browser.  The 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.  With this method, it is common (though not
required) for the RO to be the same party as the end-user, since the
client instance has to communicate the redirection URI to the end-
user.
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 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):
The client instance MUST NOT modify the URI when launching it, in
particular the client instance MUST NOT add any parameters to the
URI.  The URI MUST be reachable from the end user's browser, though
the URI MAY be opened on a separate device from the client instance
itself.  The URI MUST be accessible from an HTTP GET request and MUST
be protected by HTTPS or equivalent means.
Paragraph (version B):
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):
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 user
code.  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 client instance even if a request-
interact-callback-redirect.  If the interaction component at the user
code URI is not hosted by the AS directly, the means of communication
between the AS and this URI, including communication of the user code
itself, are out of scope for this specification.
Paragraph (version B):
When the RO enters this code at the user code URI, the AS MUST
uniquely identify the pending request that the code was associated
with.  If the AS does not recognize the entered code, the interaction
component MUST display an error to the user.  If the AS detects too
many unrecognized code enter attempts, the interaction component
SHOULD display an error to the user and MAY take additional actions
such as slowing down the input interactions.  The user should be
warned as such an error state is approached, if possible.
Paragraph (version B):
The client instance MUST NOT modify the URI when launching it, in
particular the client instance MUST NOT add any parameters to the
URI.  The user code URI MUST be reachable from the end user's
browser, though the URI is usually be opened on a separate device
from the client instance itself.  The URI MUST be accessible from an
HTTP GET request and MUST be protected by HTTPS or equivalent means.
Paragraph (version B):
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):
If an interaction response-interact-finish method is associated with
the current request, the AS MUST follow the appropriate method at
upon completion of interaction in order to signal the client instance
to continue, except for some limited error cases discussed below.  If
a finish method is not available, the AS SHOULD instruct the RO to
return to the client instance upon completion.
Paragraph (version B):
The AS MUST create an interaction reference and associate that
reference with the current interaction and the underlying pending
request.  This interaction reference value MUST be sufficiently
random so as not to be guessable by an attacker.  The interaction
reference MUST be one-time-use to prevent interception and replay
attacks.
Paragraph (version B):
The AS MUST calculate a hash value based on the client instance and
AS nonces and the interaction reference, as described in interaction-
hash.  The client instance will use this value to validate the
"finish" call.
Paragraph (version B):
The AS MUST send the hash and interaction reference based on the
interaction finish mode as described in the following sections.
Paragraph (version B):
The AS has determined that any URIs involved with the finish
method are dangerous or blocked.
Paragraph (version B):
The AS cannot determine which ongoing grant request is being
referenced.
Paragraph (version B):
The ongoing grant request has been cancelled or otherwise blocked.
Paragraph (version B):
When 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):
When using the response-interact-callback with the "push" method, 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 with the "push" method, 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 A):
To calculate the "hash" value, the party doing the calculation first
takes the "nonce" value sent by the client instance in the finish-
interaction-modes, the AS's nonce value from response-interact-
callback, and the "interact_ref" sent to the client instance'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 B):
To calculate the "hash" value, the party doing the calculation first
takes the "nonce" value sent by the client instance in the request-
interact-finish, the AS's nonce value from response-interact-finish,
and the "interact_ref" sent to the client instance'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):
While it is possible for the AS to return a response with all the
client instance's requested information (including response-token and
response-subject), it's more common that the AS and the client
instance 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 client
instance to continue negotiating the parameters of the request.
Paragraph (version B):
While it is possible for the AS to return a response with all the
client instance's requested information (including response-token and
response-subject), it's more common that the AS and the client
instance will need to communicate several times over the lifetime of
an access grant.  This is often part of facilitating authorization,
but it could also be used to allow the AS and client instance to
continue negotiating the parameters of the request.
Paragraph (version A):
When the AS responds to the client instance's "callback" parameter as
in interaction-callback, this response includes an interaction
reference.  The client instance MUST include that value as the field
"interact_ref" in a POST request to the continuation URI.
Paragraph (version B):
When the AS responds to the client instance's "finish" method as in
interaction-callback, this response includes an interaction
reference.  The client instance MUST include that value as the field
"interact_ref" in a POST request to the continuation URI.
Paragraph (version A):
When the client instance does not include a "callback" parameter, the
client instance will often need to poll the AS until the RO has
authorized the request.  To do so, the client instance makes a POST
request to the continuation URI as in continue-after-interaction, but
does not include a message body.
Paragraph (version B):
When the client instance does not include a "finish" parameter, the
client instance will often need to poll the AS until the RO has
authorized the request.  To do so, the client instance makes a POST
request to the continuation URI as in continue-after-interaction, but
does not include a message body.