Draft: draft-ietf-gnap-core-protocol

Commentary: This requirement almost one by one copied from as it 's a quite important nuance in practical usage . I suggest also renaming to ( issued at ) . Finally , I think that both attached and detached JWS proving possession mechanisms must include the " typ " header parameter with appropriate values . 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-202 - -gnap - core - protocol - editors- 
 Only normalization is handed by this PR . Could you open issues for your two other comments ? 
 We do n't have the problem in the suggested text , but we might want to tell the  authors that theirs links are incorrect ( do n't point to RFC3986 ) . 
 Seems like they have the right links but these links somehow get broken during the compilation phase by the mmark processor . Note , they define as and this specification as This is a huge difference . 
 Oh -- I thought this got changed in one of the other  fixes . It 's not an intentional difference . I 'll add an issue , there 's other DPoP - related stuff we need to clean up . 
 Actually I take it back -- I missed the context here . The JOSE - based methods are n't meant to be copies of the  claims , and there 's value in including the full URL here . The claim name should n't be the same as the  claim , though , to avoid confusion . 
 The idea is to minimize ways to reuse JWS objects . These attacks are sometimes referred as Swapping JWTs and Cross - JWT Confusion ) . See also discussion in
Paragraph (version A):
protected API (Application Programming Interface) served by a RS
and that can be accessed by a client, if and only if a valid
access token is provided.  Note: to avoid complex sentences, the
specification document may simply refer to resource instead of
protected resource.
Paragraph (version A):
ability given to a subject to perform a given operation on a
resource under the control of a RS.
Paragraph (version B):
protected API (Application Programming Interface) served by an RS
and that can be accessed by a client, if and only if a valid
access token is provided.  Note: to avoid complex sentences, the
specification document may simply refer to resource instead of
protected resource.
Paragraph (version B):
ability given to a subject to perform a given operation on a
resource under the control of an RS.
Paragraph (version A):
The client instance request.  The client instance indicates that
it can request-interact-redirect and request-interact-callback.
The client instance stores verification information for its
callback in the session created in (1).
Paragraph (version B):
The client instance request.  The client instance indicates that
it can request-interact-redirect and request-interact-callback-
redirect.  The client instance stores verification information for
its redirect in the session created in (1).
Paragraph (version A):
When the AS is done interacting with the user, the AS interaction-
callback to the client instance using the callback URL provided in
(2).  The callback URL is augmented with an interaction reference
that the AS associates with the ongoing request created in (2) and
referenced in (4).  The callback URL is also augmented with a hash
of the security information provided in (2) and (3).  The client
instance loads the verification information from (2) and (3) from
the session created in (1).  The client instance interaction-hash
based on this information and continues only if the hash
validates.  Note that the client instance needs to ensure that the
parameters for the incoming request match those that it is
expecting from the session created in (1).  The client instance
also needs to be prepared for the end-user never being returned to
the client instance and handle time outs appropriately.
Paragraph (version B):
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 A):
the client instance and handle time outs appropriately.
Paragraph (version B):
the client instance and handle timeouts appropriately.
Paragraph (version B):
The "interact" field is a JSON object with three keys whose values
declare how the client can initiate and complete the request, as well
as provide hints to the AS about user preferences such as locale.  A
client instance MUST NOT declare an interaction mode it does not
support.  The client instance MAY send multiple modes in the same
request.  There is no preference order specified in this request.  An
AS MAY response-interact in a request, depending on its capabilities
and what is allowed to fulfill the request.
Paragraph (version B):
Indicates how the client instance can start an interaction.
Paragraph (version B):
Indicates how the client instance can receive an indication that
interaction has finished at the AS.
Paragraph (version B):
Provides additional information to inform the interaction process
at the AS.
Paragraph (version B):
The "interact" field MUST contain the "start" key, and MAY contain
the "finish" and "hints" keys.  The value of each key is an array
which contains strings or JSON objects as defined below.
Paragraph (version A):
Indicates that the client instance can receive a callback from the
AS after interaction with the RO has concluded.
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 through a browser request.
Paragraph (version A):
In this non-normative example, the client instance is indicating that
it can display a request-interact-usercode and direct the end-user to
an request-interact-redirect on a secondary device, but it cannot
accept a callback.
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 B):
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 display a request-interact-usercode and direct the end-user to
an request-interact-redirect on a secondary device, but it cannot
accept a redirect or push callback.
Paragraph (version A):
If the client instance is capable of receiving a message from the AS
indicating that the RO has completed their interaction, the client
instance indicates this by sending the "callback" field.  The value
of this field is an object containing the following members.
Paragraph (version A):
REQUIRED.  Indicates the URI to send the RO to after interaction.
This URI MAY be unique per request and MUST be hosted by or
accessible by the client instance.  This URI MUST NOT contain any
fragment component.  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.  If the client instance needs
any state information to tie to the front channel interaction
response, it MUST use a unique callback URI to link to that
ongoing state.  The allowable URIs and URI patterns MAY be
restricted by the AS based on the client instance's presented key
information.  The callback URI SHOULD be presented to the RO
during the interaction phase before redirect.
Paragraph (version B):
If the client instance is capable of receiving a message from the AS
indicating that the RO has completed their interaction, the client
instance indicates this by sending the following members of an object
under the "finish" key.
Paragraph (version B):
REQUIRED.  Indicates the URI that the AS will either send the RO
to after interaction or send an HTTP POST request.  This URI MAY
be unique per request and MUST be hosted by or accessible by the
client instance.  This URI MUST NOT contain any fragment
component.  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.  If the client instance needs any
state information to tie to the front channel interaction
response, it MUST use a unique callback URI to link to that
ongoing state.  The allowable URIs and URI patterns MAY be
restricted by the AS based on the client instance's presented key
information.  The callback URI SHOULD be presented to the RO
during the interaction phase before redirect.
Paragraph (version A):
A callback "method" value of "redirect" indicates that the client
instance will expect a call from the RO's browser using the HTTP
method GET as described in interaction-callback.
Paragraph (version B):
A finish "method" value of "redirect" indicates that the client
instance will expect a request from the RO's browser using the HTTP
method GET as described in interaction-callback.
Paragraph (version A):
A callback "method" value of "push" indicates that the client
instance will expect a call from the AS directly using the HTTP
method POST as described in interaction-pushback.
Paragraph (version B):
A finish "method" value of "push" indicates that the client instance
will expect a request from the AS directly using the HTTP method POST
as described in interaction-pushback.
Paragraph (version B):
The "hints" key is an object describing one or more suggestions from
the client instance that the AS can use to help drive user
interaction.
Paragraph (version A):
An identifier this client instance instance can use to identify
itself when making future requests.
Paragraph (version A):
An identifier this client instance instance can use to identify
its current end-user when making future requests.
Paragraph (version B):
An identifier this client instance can use to identify itself when
making future requests.
Paragraph (version B):
An identifier this client instance can use to identify its current
end-user when making future requests.
Paragraph (version A):
Callback to a client instance accessible URL after interaction is
completed.
Paragraph (version B):
A nonce used by the client instance to verify the callback after
interaction is completed.
Paragraph (version A):
If the client instance indicates that it can request-interact-
callback and the AS supports this mode for the client instance's
request, the AS responds with a "callback" field containing a nonce
that the client instance will use in validating the callback as
defined in interaction-callback.
Paragraph (version A):
When the RO completes interaction at the AS, the AS MUST call the
client instance's callback URL using the method indicated in the
request-interact-callback as described in interaction-callback.
Paragraph (version A):
If the AS returns a "callback" nonce, the client instance MUST NOT
continue a grant request before it receives the associated
interaction reference on the callback URI.
Paragraph (version B):
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 B):
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 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.
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.
Paragraph (version B):
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):
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.
Paragraph (version B):
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):
When using the response-interact-callback with the "redirect" method,
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 callback URL sent in request-
interact-callback-redirect.
Paragraph (version A):
The AS secures this callback by adding the hash and interaction
reference as query parameters to the client instance's callback URL.
Paragraph (version B):
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 secures this redirect by adding the hash and interaction
reference as query parameters to the client instance's redirect URL.
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 request-
interact-callback, 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 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 A):
If the client instance needs to get the current state of an ongoing
grant request, it makes an HTTP GET request to the continuation URI.
This request MUST NOT alter the grant request in any fashion,
including causing the issuance of new access tokens or modification
of interaction parameters.
Paragraph (version A):
The AS MAY include existing access tokens and previously-released
subject claims in the response.  The AS MUST NOT issue a new access
token or release a new subject claim in response to this request.
Paragraph (version A):
The response MAY include any fields described response that are
applicable to this ongoing request, including the most recently
issued access tokens, any released subject claims, and any currently
active interaction modes.  The response MAY contain a new response-
continue as described above.