Draft: draft-ietf-gnap-core-protocol

Commentary: Includes changes through section 3 
 To edit notification comments on pull requests , go to your . 
 thanks for the great feedback -- I believe all items have been addressed , please re - review . 
 Thanks , great work ! I think we can merge .
Paragraph (version A):
GNAP defines a mechanism for delegating authorization to a piece of
software, and conveying that delegation to the software.  This
delegation can include access to a set of APIs as well as information
passed directly to the software.
Paragraph (version A):
This protocol allows a piece of software, the client instance, to
request delegated authorization to resource servers and to request
direct subject information.  This delegation is facilitated by an
authorization server usually on behalf of a resource owner.  The end
user operating the software may interact with the authorization
server to authenticate, provide consent, and authorize the request.
Paragraph (version B):
GNAP defines a mechanism for delegating authorization to a piece of
software, and conveying the results and artifacts of that delegation
to the software.  This delegation can include access to a set of APIs
as well as subject information passed directly to the software.
Paragraph (version B):
This protocol allows a piece of software, the client instance, to
request delegated authorization to resource servers and subject
information.  This delegation is facilitated by an authorization
server usually on behalf of a resource owner.  The end user operating
the software can interact with the authorization server to
authenticate, provide consent, and authorize the request as a
resource owner.
Paragraph (version A):
This specification focuses on the portions of the delegation process
facing the client instance.  In particular, this specification
defines interoperable methods for a client instance to request,
negotiate, and receive access to information facilitated by the
authorization server.  This specification also discusses discovery
mechanisms for the client instance to configure itself dynamically.
The means for an authorization server and resource server to
interoperate are discussed in the companion document, I-D.ietf-gnap-
resource-servers.
Paragraph (version B):
This specification focuses on the portions of the delegation process
facing the client instance.  In particular, this specification
defines interoperable methods for a client instance to request,
negotiate, and receive access to information facilitated by the
authorization server.  This specification additionally defines
methods for the client instance to access protected resources at a
resource server.  This specification also discusses discovery
mechanisms for the client instance to configure itself dynamically.
The means for an authorization server and resource server to
interoperate are discussed in the companion document, I-D.ietf-gnap-
resource-servers.
Paragraph (version A):
A single role need not be deployed as a monolithic service.  For
example, a client instance could have components that are installed
on the end user's device as well as a back-end system that it
communicates with.  If both of these components participate in the
delegation protocol, they are both considered part of the client
instance.  If there are several copies of the client software that
run separately but all share the same key material, such as a
deployed cluster, then this cluster is considered a single client
instance.
Paragraph (version A):
In these cases, the distinct components of what is considered a GNAP
client instance may use any number of different communication
mechanisms between them, all of which would be considered an
implementation detail of the client instances and out of scope of
GNAP.
Paragraph (version B):
A single role need not be deployed as a monolithic service.  For
example, a client instance could have components that are installed
on the end user's device as well as a back-end system that it
communicates with.  If both of these components participate in the
delegation protocol, they are both considered part of the client
instance.  If there are several copies of the client software that
run separately but all share the same key material, such as a
deployed cluster, then this cluster is considered a single client
instance.  In these cases, the distinct components of what is
considered a GNAP client instance may use any number of different
communication mechanisms between them, all of which would be
considered an implementation detail of the client instances and out
of scope of GNAP.
Paragraph (version A):
AS/RO: the AS is expected to follow the decisions made by the RO,
either through interactive consent requests, repeated interactions
or automated rules (as described in sequence).  Privacy
considerations aim to reduce the risk of an honest but too curious
AS, or the consequences of an unexpected user data exposure.
Paragraph (version B):
AS/RO: the AS is expected to follow the decisions made by the RO,
either through interactive consent requests, repeated
interactions, or automated rules (as described in sequence).
Privacy considerations aim to reduce the risk of an honest but
too-curious AS, or the consequences of an unexpected user data
exposure.
Paragraph (version A):
A formal trust model is out of scope of this specification, but might
be carried out thanks to promise-theory.
Paragraph (version B):
A formal trust model is out of scope of this specification, but one
could be developed using techniques such as promise-theory.
Paragraph (version A):
The following sections and examples contain specific guidance on how
to use GNAP in different situations and deployments.  For example, it
is possible for the client instance to never request an access token
and never call an RS, just as it is possible for there not to be a
user involved in the delegation process.
Paragraph (version B):
The following sections and examples contain specific guidance on how
to use GNAP in different situations and deployments.  For example, it
is possible for the client instance to never request an access token
and never call an RS, just as it is possible to have no end user
involved in the delegation process.
Paragraph (version A):
The client instance establishes a verifiable session to the user,
in the role of the end user.
Paragraph (version B):
The client instance establishes a session with the user, in the
role of the end user.
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 URI.  The user enters the code
at a URI that 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 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 user enters the code
at a URI that 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.
Note that since the user is not assumed to be interacting with the
client instance through the same web browser used for interaction at
the AS, the user is not shown as being connected to the client
instance in this diagram.
Paragraph (version A):
The client instance request.  The client instance does not send
any interaction modes to the server, indicating that it does not
expect to interact with the RO.  The client instance can also
signal which RO it requires authorization from, if known, by using
the request-user.  It's also possible for the AS to determine
which RO needs to be contacted by the nature of what access is
being requested.
Paragraph (version B):
The client instance request.  The client instance does not send
any interaction modes to the server, indicating that it does not
expect to interact with the RO.  The client instance can also
signal which RO it requires authorization from, if known, by using
the request-subject and request-user sections.  It's also possible
for the AS to determine which RO needs to be contacted by the
nature of what access is being requested.
Paragraph (version A):
The AS determines which RO to contact based on the request in (1),
through a combination of the request-user, the request-token, and
other policy information.  The AS contacts the RO and
authenticates them.
Paragraph (version B):
The AS determines which RO to contact based on the request in (1),
through a combination of the request-user, the request-subject,
the request-token, and other policy information.  The AS contacts
the RO and authenticates them.
Paragraph (version A):
The AS determines that the request has been authorized, the AS
grants access to the resource in the form of response-token to the
client instance.  Note that response-subject is not generally
applicable in this use case, as there is no user involved.
Paragraph (version B):
The AS determines that the request has been authorized based on
the identity of the client instance making the request and the
request-token.  The AS grants access to the resource in the form
of response-token to the client instance.  Note that response-
subject is not generally applicable in this use case, as there is
no user involved.
Paragraph (version A):
The AS validates the rotation request including the signature and
keys presented in (5) and returns a response-token-single.  The
response includes a new access token and can also include updated
token management information, which the client instance will store
in place of the values returned in (2).
Paragraph (version B):
The AS validates the rotation request including the signature and
keys presented in (7) and returns a response-token-single.  The
response includes a new access token and can also include updated
token management information, which the client instance will store
in place of the values returned in (2).
Paragraph (version A):
In this scenario, the end user and resource owner are two different
people.  In this scenario, the client instance already knows who the
end user is, likely through a separate authentication process.  The
end user, operating the client instance, needs to get subject
information about another person in the system, the RO.  The RO is
given an opportunity to release this information using an
asynchronous interaction method with the AS.  This scenario would
apply, for instance, when the end user is an agent in a call-center
and the resource owner is a customer authorizing the call center
agent to access their account on their behalf.
Paragraph (version A):
Precondition: The end user is authenticated to the client instance,
and the client instance has an identifier representing the end user
that it can present to the AS.  This identifier should be unique to
the particular session with the client instance and the AS.
Paragraph (version B):
In this scenario, the end user and resource owner are two different
people.  Here, the client instance already knows who the end user is,
likely through a separate authentication process.  The end user,
operating the client instance, needs to get subject information about
another person in the system, the RO.  The RO is given an opportunity
to release this information using an asynchronous interaction method
with the AS.  This scenario would apply, for instance, when the end
user is an agent in a call-center and the resource owner is a
customer authorizing the call center agent to access their account on
their behalf.
Paragraph (version B):
Precondition: The end user is authenticated to the client instance,
and the client instance has an identifier representing the end user
that it can present to the AS.  This identifier should be unique to
the particular session with the client instance and the AS.  The
client instance is also known to the AS and allowed to access this
advanced functionality where the information of someone other than
the end user is returned to the client instance.
Paragraph (version A):
The AS sees that the identifier for the end user and subject being
requested are different.  The AS determines that it can reach out
to the RO asynchronously for approval.  While it is doing so, the
AS returns a response-continue with a "finish" nonce to allow the
client instance to keep polling after interaction with the RO has
concluded.
Paragraph (version B):
The AS sees that the identifier for the end user and subject being
requested are different.  The AS determines that it can reach out
to the RO asynchronously for approval.  While it is doing so, the
AS returns a response-continue with a "finish" nonce to allow the
client instance to continue the grant request after interaction
with the RO has concluded.
Paragraph (version A):
To start a request, the client instance sends a RFC8259 document with
an object as its root.  Each member of the request object represents
a different aspect of the client instance's request.  Each field is
described in detail in a section below.
Paragraph (version B):
To start a request, the client instance sends an HTTP POST with a
RFC8259 document to the grant endpoint of the AS.  The grant endpoint
is a URI that uniquely identifies the AS to client instances and
serves as the identifier for the AS.  The document is a JSON object
where each field represents a different aspect of the client
instance's request.  Each field is described in detail in a section
below.
Paragraph (version A):
The authorization server MUST include the HTTP "Cache-Control"
response header field RFC7234 with a value set to "no-store".
Paragraph (version A):
The AS SHOULD NOT re-use subject identifiers for multiple different
ROs.
Paragraph (version A):
The "formats" and "assertions" request fields are independent of each
other, and a returned assertion MAY use a different subject
identifier than other assertions and subject identifiers in the
response.  All subject identifiers and assertions returned MUST refer
to the same person.
Paragraph (version A):
When sending a non-continuation request to the AS, the client
instance MUST identify itself by including the "client" field of the
request and by signing the request as described in binding-keys.
Note that for a continue-request, the client instance is identified
by its association with the request being continued and so this field
is not sent under those circumstances.
Paragraph (version B):
states, the AS can determine which client is associated with the
grant by dereferencing the continuation access token sent in the
continue-request.  As a consequence, the "client" field is not sent
or accepted for continuation requests.
Paragraph (version B):
Client information MUST either be sent by value as an object or by
reference as a string (see request-instance).
Paragraph (version A):
If the client instance knows the identity of the end user through one
or more identifiers or assertions, the client instance MAY send that
information to the AS in the "user" field.  The client instance MAY
pass this information by value or by reference.
Paragraph (version B):
If the client instance knows the identity of the end user through one
or more identifiers or assertions, the client instance MAY send that
information to the AS in the "user" field.  The client instance MAY
pass this information by value or by reference (See request-user-
reference).
Paragraph (version A):
If the identified end user does not match the RO present at the AS
during an interaction step, the AS SHOULD reject the request with an
"unknown_user" error (response-error).
Paragraph (version A):
If the AS trusts the client instance to present verifiable
assertions, the AS MAY decide, based on its policy, to skip
interaction with the RO, even if the client instance provides one or
more interaction modes in its request.
Paragraph (version B):
If the identified end user does not match the RO present at the AS
during an interaction step, and the AS is not explicitly allowing a
cross-user authorization, the AS SHOULD reject the request with an
"unknown_user" error (response-error).
Paragraph (version B):
If the AS trusts the client instance to present verifiable assertions
or known subject identifiers, such as an opaque identifier issued by
the AS for this specific client instance, the AS MAY decide, based on
its policy, to skip interaction with the RO, even if the client
instance provides one or more interaction modes in its request.
Paragraph (version B):
In this non-normative example, the client instance is indicating that
it can not start any interaction with the end-user, but that the AS
can request-interact-callback-push when authorization from the RO is
received asynchronously.
Paragraph (version A):
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 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 grant endpoint URI.
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 URI
payload response-interact-app.  The client instance manages this
interaction method as described in interaction-app.
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 URI that
does not change at runtime.  The client instance has no reasonable
means to communicate a dynamic URI to the RO, and so this URI is
usually communicated out of band to the RO through documentation or
other messaging outside of GNAP.  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 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.  The client instance has no reasonable
means to communicate a dynamic URI to the RO, and so this URI is
usually communicated out of band to the RO through documentation or
other messaging outside of GNAP.  While this URI is generally hosted
at the AS, the client instance can make no assumptions about its
contents, composition, or relationship to the grant endpoint URI.
Paragraph (version A):
If the client instance is capable of displaying or otherwise
communicating a short, human-entered code along with a short, human-
entered URI to the RO, the client instance indicates this by
including "user_code_uri" in the array under the "start" key.  This
code is to be entered at the dynamic URL given in the response.
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 along with a short, human-
entered URI to the RO, the client instance indicates this by
including "user_code_uri" in the array under the "start" key.  This
code is to be entered at the dynamic URL given in the response.
While this URL is generally hosted at the AS, the client instance can
make no assumptions about its contents, composition, or relationship
to the grant endpoint URI.
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-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 B):
If interaction finishing is supported for this client instance and
request, the AS response-interact-finish used by the client instance
to validate the callback.  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 B):
The client instance's 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.
Paragraph (version B):
The client instance's URI MUST be an HTTP URI and MUST be protected
by HTTPS or equivalent.
Paragraph (version A):
If the AS determines that the request can be continued with
additional requests, it responds with the "continue" field.  This
field contains a JSON object with the following properties.
Paragraph (version B):
The response MUST be sent as a JSON object in the body of the HTTP
response with Content-Type "application/json", unless otherwise
specified by the specific response (eg, an empty response with no
Content-Type).
Paragraph (version B):
The authorization server MUST include the HTTP Cache-Control response
header field RFC7234 with a value set to "no-store".
Paragraph (version B):
If the AS determines that the grant request can be continued by the
client instance, the AS responds with the "continue" field.  This
field contains a JSON object with the following properties.
Paragraph (version B):
If the "bearer" flag and the "key" field in this response are
omitted, the token is bound the request-client in its request for
access.  If the "bearer" flag is omitted, and the "key" field is
present, the token is bound to the key and proofing mechanism
indicated in the "key" field.  The means by which the AS determines
how to bind an access token to a key other than that presented by the
client instance is out of scope for this specification, but common
practices include pre-registering specific keys in a static fashion.
Paragraph (version B):
The client software MUST reject any access token where the "flags"
field contains the "bearer" flag and the "key" field is present with
any value.
Paragraph (version A):
The multiple access token response MUST be used when multiple access
tokens are requested, even if only one access token is issued as a
result of the request.  The AS MAY refuse to issue one or more of the
requested access tokens, for any reason.  In such cases the refused
token is omitted from the response and all of the other issued access
tokens are included in the response the requested names appropriate
names.
Paragraph (version A):
If the client instance request-token-multiple, the AS MUST NOT
respond with a single access token structure, even if only a single
access token is granted.  In such cases, the AS responds with a
multiple access token structure containing one access token.
Paragraph (version A):
Each access token MAY be bound to different keys with different
proofing mechanisms.
Paragraph (version A):
The "manage" URI MUST NOT contain the access token "value".
Paragraph (version B):
The AS MAY refuse to issue one or more of the requested access
tokens, for any reason.  In such cases the refused token is omitted
from the response and all of the other issued access tokens are
included in the response the requested names appropriate names.  If
the client instance request-token-multiple, the AS MUST NOT respond
with a single access token structure, even if only a single access
token is granted.  In such cases, the AS MUST respond with a multiple
access token structure containing one access token.
Paragraph (version B):
The parameters of each access token are separate.  For example, each
access token is expected to have a unique value and (if present)
label, and likely has different access rights associated with it.
Each access token could also be bound to different keys with
different proofing mechanisms.
Paragraph (version B):
The URI returned is a function of the AS, but the URI itself MAY be
completely distinct from the grant endpoint URI that the client
instance uses to request, allowing an AS to separate its user-
interactive functionality from its back-end security functionality.
The AS will need to dereference the specific grant request and its
information from the URI alone.  If the AS does not directly host the
functionality accessed through the redirect URI, then the means for
the interaction functionality to communicate with the rest of the AS
are out of scope for this specification.
Paragraph (version A):
If the client instance indicates that it can request-interact-
usercode and the AS supports this mode for the client instance's
request, the AS responds with a "user_code" field.  This field is
string containing a unique short code that the user can type into a
web page.  This string MUST be case-insensitive, MUST consist of only
easily typeable characters (such as letters or numbers).  The time in
which this code will be accepted SHOULD be short lived, such as
several minutes.  It is RECOMMENDED that this code be no more than
eight characters in length.  REQUIRED.
Paragraph (version B):
If the client instance indicates that it can request-interact-
usercode and the AS supports this mode for the client instance's
request, the AS responds with a "user_code" field.  This field is
string containing a unique short code that the user can type into a
web page.  This string MUST be case-insensitive, MUST consist of only
easily typeable characters (such as letters or numbers).  The time in
which this code will be accepted SHOULD be short lived, such as
several minutes.  It is RECOMMENDED that this code be no more than
eight characters in length.
Paragraph (version A):
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.  If the
client instance is capable of communicating an short arbitrary URI to
the end user for use with the user code, the client instance can
instead use the request-interact-usercodeuri method instead.  If the
client instance is capable of communicating a long 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 B):
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 where the code is entered.  If the
client instance is capable of communicating an short arbitrary URI to
the end user for use with the user code, the client instance SHOULD
instead use the request-interact-usercodeuri mode.  If the client
instance is capable of communicating a long arbitrary URI to the end
user, such as through a scannable code, the client instance SHOULD
use the request-interact-redirect mode for this purpose instead of or
in addition to the user code mode.
Paragraph (version B):
The URI returned is a function of the AS, but the URI itself MAY be
completely distinct from the grant endpoint URI that the client
instance uses to request, allowing an AS to separate its user-
interactive functionality from its back-end security functionality.
If the AS does not directly host the functionality accessed through
the given URI, then the means for the interaction functionality to
communicate with the rest of the AS are out of scope for this
specification.
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 URI using the method indicated in the request-interact-
finish as described in interaction-finish.
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.  See details in interaction-finish.
Paragraph (version B):
When the interaction is completed, the interaction component of the
AS MUST contact the client instance using the means defined by the
finish method as described in interaction-finish.
Paragraph (version B):
If the AS returns the finish field, 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):
This field is an object with the following OPTIONAL properties.
Paragraph (version A):
Subject identifiers returned by the AS SHOULD uniquely identify the
RO at the AS.  Some forms of subject identifier are opaque to the
client instance (such as the subject of an issuer and subject pair),
while others forms (such as email address and phone number) are
intended to allow the client instance to correlate the identifier
with other account information at the client instance.  The AS MUST
ensure that the returned subject identifiers only apply to the
authenticated end user.  The client instance MUST NOT request or use
any returned subject identifiers for communication purposes (see
request-subject).  That is, a subject identifier returned in the
format of an email address or a phone number only identifies the RO
to the AS and does not indicate that the AS has validated that the
represented email address or phone number in the identifier is
suitable for communication with the current user.  To get such
information, the client instance MUST use an identity protocol to
request and receive additional identity claims.  The details of an
identity protocol and associated schema are outside the scope of this
specification.
Paragraph (version A):
The client instance MUST interpret all subject information in the
context of the AS that the subject information is received from, as
is discussed in Section 6 of SP80063C.  For example, one AS could
return an email identifier of "user@example" for one account, and a
different AS could return that same email identifier of
"user@example" for a completely different account.  A client instance
talking to both AS's needs to differentiate between these two
accounts by accounting for the AS source of each identifier.
Paragraph (version B):
This field is an object with the following properties.
Paragraph (version B):
Subject identifiers returned by the AS SHOULD uniquely identify the
RO at the AS.  Some forms of subject identifier are opaque to the
client instance (such as the subject of an issuer and subject pair),
while others forms (such as email address and phone number) are
intended to allow the client instance to correlate the identifier
with other account information at the client instance.  The client
instance MUST NOT request or use any returned subject identifiers for
communication purposes (see request-subject).  That is, a subject
identifier returned in the format of an email address or a phone
number only identifies the RO to the AS and does not indicate that
the AS has validated that the represented email address or phone
number in the identifier is suitable for communication with the
current user.  To get such information, the client instance MUST use
an identity protocol to request and receive additional identity
claims.  The details of an identity protocol and associated schema
are outside the scope of this specification.
Paragraph (version B):
The AS MUST ensure that the returned subject information represents
the RO.  In most cases, the AS will also ensure that the returned
subject information represents the end user authenticated
interactively at the AS.  The AS SHOULD NOT re-use subject
identifiers for multiple different ROs.
Paragraph (version B):
The "sub_ids" and "assertions" response fields are independent of
each other.  That is, a returned assertion MAY use a different
subject identifier than other assertions and subject identifiers in
the response.  However, all subject identifiers and assertions
returned MUST refer to the same party.
Paragraph (version B):
The client instance MUST interpret all subject information in the
context of the AS that the subject information is received from, as
is discussed in Section 6 of SP80063C.  For example, one AS could
return an email identifier of "user@example.com" for one RO, and a
different AS could return that same email identifier of
"user@example.com" for a completely different RO.  A client instance
talking to both AS's needs to differentiate between these two
accounts by accounting for the AS source of each identifier.
Paragraph (version B):
If the AS determines that the request cannot be completed for any
reason, it responds to the client instance with an "error" field in
the response message.  This field is either an object or a string.
Paragraph (version A):
If an error is returned and the client instance can continue, the AS
MAY include the "continue" field in the response, as defined
response-continue.  This allows the client instance to modify its
request for access, potentially leading to prompting the RO again.
Other fields MUST NOT be included in the response.
Paragraph (version B):
state (and therefore the client instance can continue), the AS MAY
include the "continue" field in the response along with the "error",
as defined response-continue.  This allows the client instance to
modify its request for access, potentially leading to prompting the
RO again.  Other fields MUST NOT be included in the response.
Paragraph (version A):
state, 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):
state, 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, and how those
are applied to the grant request.
Paragraph (version B):
The authorization and consent gathering process in GNAP is left
deliberately flexible to allow for a wide variety of different
deployments, interactions, and methodologies.  In this process, the
AS can gather consent from the RO or apply the RO's policy as
necessitated by the access that has been requested.  The AS can
sometimes determine which RO needs to prompt for consent based on
what has been requested by the client instance, such as a specific RS
record, an identified subject, or a request requiring specific access
such as approval by an administrator.  In other cases, the request is
applied to whichever RO is present at the time of consent gathering.
This pattern is especially prevalent when the end user is sent to the
AS for an interactive session, during which the end user takes on the
role of the RO.  In these cases, the end user is delegating their own
access as RO to the client instance.
Paragraph (version B):
The client instance can 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.  Here, the AS
usually needs to interact directly with the end user to determine
their identity, 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.
Paragraph (version B):
The client instance MUST use each interaction method at most once.
The AS SHOULD handle any interact request as a one-time-use mechanism
and SHOULD apply suitable timeouts to any interaction start methods
provided, including user codes and redirection URIs.  The client
instance SHOULD apply suitable timeouts to any interaction finish
method.
Paragraph (version B):
If the AS instead has a means of contacting the RO directly, it could
do so without involving the client instance in its consent gathering
process.  For example, the AS could push a notification to a known RO
and have the RO approve the pending request asynchronously.  These
interactions can be through an interface of the AS itself (such as a
hosted web page), through another application (such as something
installed on the RO's device), through a messaging fabric, or any
other means.
Paragraph (version A):
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.
Paragraph (version A):
The RO is also allowed to define a policy at the AS to determine
which kind of end user can get access to the resource, and under
which condition.  For instance, such a condition might require the
end user login and the acceptance of the RO's legal provisions.
Alternatively, client software could be acting without an end user,
and the RO's policy allows issuance of access tokens to instances of
that client software without human interaction.
Paragraph (version A):
The details of determining which RO's or related policies are
required for a given request are out of scope for this specification.
Paragraph (version A):
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 A):
The AS SHOULD handle any interact request as a one-time-use mechanism
and SHOULD apply suitable timeouts to any interaction start methods
provided, including user codes and redirection URIs.  The client
instance SHOULD apply suitable timeouts to any interaction finish
method.
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 some circumstances, the AS could even determine
that the end user present during the interaction is not the
appropriate RO for a given request and reach out to the appropriate
RO asynchronously.
Paragraph (version B):
The RO is also allowed to define an automated policy at the AS to
determine which kind of end user can get access to the resource, and
under which condition.  For instance, such a condition might require
the end user login and the acceptance of the RO's legal provisions.
Alternatively, client software could be acting without an end user,
and the RO's policy allows issuance of access tokens to specific
instances of that client software without human interaction.
Paragraph (version B):
While all of these cases are supported by GNAP, the details of their
implementation, and for determining which RO's or related policies
are required for a given request, are out of scope for this
specification.
Paragraph (version A):
state, the interaction start methods sent by the client instance can
be used to facilitate interaction with the end user.  To initiate an
interaction start method indicated by the response-interact from the
AS, the client instance follows the steps defined by that interaction
start mode.  The actions of the client instance required for the
interaction start modes defined in this specification are described
in the following sections.  Interaction start modes defined in
extensions to this specification MUST define the expected actions of
the client software.
Paragraph (version A):
If the client instance does not start an interaction start mode
within an AS-determined amount of time, the AS SHOULD reject attempts
to use the interaction start modes.  If the client instance has
already begun one interaction start mode, the AS SHOULD reject
attempts to use other interaction start modes.
Paragraph (version B):
state, the interaction start methods sent by the client instance can
be used to facilitate interaction with the end user.  To initiate an
interaction start method indicated by the response-interact from the
AS, the client instance follows the steps defined by that interaction
start mode.  The actions of the client instance required for the
interaction start modes defined in this specification are described
in the following sections.  Interaction start modes defined in
extensions to this specification MUST define the expected actions of
the client software when that interaction start mode is used.
Paragraph (version B):
If the client instance does not start an interaction start mode
within an AS-determined amount of time, the AS SHOULD reject attempts
to use the interaction start modes.  If the client instance has
already begun one interaction start mode, the AS SHOULD reject
attempts to use other interaction start modes.  For example, if a
user code has been successfully entered for a grant request, the AS
will probably want to reject requests to an arbitrary redirect URI on
the same grant request.
Paragraph (version A):
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):
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.  In all cases, the URI is accessed with an
HTTP GET request, and the resulting page is assumed to allow direct
interaction with the end user through an HTTP user agent.  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 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.  The URI value is used to identify the
grant request being authorized.  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 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.  The URI value is used to identify the
grant request being authorized.  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 the service provided by 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 communicate or facilitate launching an arbitrary URI.
The associated URI could be statically configured with the client
instance or in the client software's documentation.  As a
consequence, these URIs SHOULD be short.  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.  Since
it is designed to be typed in, the URI SHOULD 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 designed to be used when the
client instance is not able to communicate or facilitate launching an
arbitrary URI.  The associated URI could be statically configured
with the client instance or in the client software's documentation.
As a consequence, these URIs SHOULD be short.  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 A):
When the end user is directed to enter a short code through the
response-interact-usercodeuri mode, the client instance communicates
the user code and associated URI to the end user and directs the end
user to enter that code at the URI.  This mode is used when the
client instance is not able to facilitate launching an arbitrary URI
but can communicate arbitrary values like URIs.  As a consequence,
these URIs SHOULD be short.  The client instance MUST NOT modify the
URI when communicating it to the end user; 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.  Since it is designed to be typed in, the URI SHOULD 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-usercodeuri mode, the client instance communicates
the user code and associated URI to the end user and directs the end
user to enter that code at the URI.  This mode is used when the
client instance is not able to facilitate launching a complex
arbitrary URI but can communicate arbitrary values like URIs.  As a
consequence, these URIs SHOULD be short to allow the URI to be typed
by the end user.  The client instance MUST NOT modify the URI when
communicating it to the end user; 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 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 URI sent in request-interact-callback-redirect.
Paragraph (version B):
When using the "redirect" interaction finish method defined in
request-interact-callback-redirect and 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.
Paragraph (version A):
When receiving the request, the client instance MUST parse the query
parameters to calculate and validate the hash value as described in
interaction-hash, or else return an "unknown_interaction" error
(response-error).  If the hash validates, the client instance sends a
continuation request to the AS as described in continue-after-
interaction using the interaction reference value received here.
Paragraph (version A):
When using the response-interact-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 B):
The client instance MUST be able to process a request on the URI.  If
the URI is HTTP, the request MUST be an HTTP GET.
Paragraph (version B):
When receiving the request, the client instance MUST parse the query
parameters to extract the hash and interaction reference values.  The
client instance MUST calculate and validate the hash value as
described in interaction-hash.  If the hash validates, the client
instance sends a continuation request to the AS as described in
continue-after-interaction using the interaction reference value
received here.  If the hash does not validate, the client instance
MUST NOT send the interaction reference to the AS.
Paragraph (version B):
When using the "push" interaction finish method defined in request-
interact-callback-redirect and 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.
Paragraph (version A):
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 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 as discussed in security-
interact-hash and related sections.  The AS MUST always provide this
hash, and the client instance MUST validate the hash when received.
Paragraph (version A):
There is no padding or whitespace before or after any of the lines,
and no trailing newline character.
Paragraph (version A):
The party then hashes this string with the appropriate algorithm
based on the "hash_method" parameter under the "finish" key.  The
resulting byte array from the hash function is then encoded using
URL-Safe Base64 with no padding RFC4648.  The resulting string is the
hash value.
Paragraph (version A):
The "hash_method" value MUST be one of the hash name strings defined
in the IANA Named Information Hash Algorithm Registry [1].
Paragraph (version A):
If the "hash_method" value is not present in the client instance's
request, the algorithm defaults to "sha-256".
Paragraph (version A):
The "sha-256" hash method consists of hashing the input string with
the 256-bit SHA2 algorithm.  The byte array is then encoded using
URL-Safe Base64 with no padding RFC4648.  The resulting string is the
hash value.
Paragraph (version A):
The "sha3-512" hash method consists of hashing the input string with
the 512-bit SHA3 algorithm.  The byte array is then encoded using
URL-Safe Base64 with no padding RFC4648.  The resulting string is the
hash value.
Paragraph (version A):
state.  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 through modification of the
request.
Paragraph (version A):
To enable this ongoing negotiation, the AS provides a continuation
API to the client software.  The AS returns a "continue" field
response-continue that contains information the client instance needs
to access this API, including a URI to access as well as a
continuation access token to use during the requests.
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 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 B):
There is no padding or whitespace before or after any of the lines,
and no trailing newline character.  The following example shows a
constructed hash base string consisting of these four elements.
Paragraph (version B):
The party then hashes this string with the appropriate algorithm
based on the "hash_method" parameter under the "finish" key of the
request-interact-finish.  The resulting byte array from the hash
function is then encoded using URL-Safe Base64 with no padding
RFC4648.  The resulting string is the hash value.
Paragraph (version B):
If provided, the "hash_method" value MUST be one of the hash name
strings defined in the IANA Named Information Hash Algorithm Registry
[1].  If the "hash_method" value is not present in the client
instance's request, the algorithm defaults to "sha-256".
Paragraph (version B):
For example, the "sha-256" hash method consists of hashing the input
string with the 256-bit SHA2 algorithm.  The following is the encoded
"sha-256" hash of the above example hash base string.
Paragraph (version B):
For another example, the "sha3-512" hash method consists of hashing
the input string with the 512-bit SHA3 algorithm.  The following is
the encoded "sha3-512" hash of the above example hash base string.
Paragraph (version B):
state and require communication with the client instance several
times over the lifetime of a grant request.  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 through modification of the request.
Paragraph (version B):
The continuation access token is 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 response from the AS is a JSON object and MAY contain any of the
fields described in response, as described in more detail in the
sections below.
Paragraph (version A):
If the AS determines that the client instance can make a further
continuation request, the AS MUST include a new response-continue.
The new "continue" response MUST include a continuation access token
as well, and this token SHOULD be a new access token, invalidating
the previous access token.  If the AS does not return a new
"continue" response, the client instance MUST NOT make an additional
continuation request.  If a client instance does so, the AS MUST
return an "invalid_continuation" error (response-error).
Paragraph (version B):
The response from the AS is a JSON object of a grant response and MAY
contain any of the fields described in response, as described in more
detail in the sections below.
Paragraph (version B):
If the AS determines that the client instance can make further
requests to the continuation API, the AS MUST include a new response-
continue.  The new "continue" response MUST include a continuation
access token as well, and this token SHOULD be a new access token,
invalidating the previous access token.  If the AS does not return a
new "continue" response, the client instance MUST NOT make an
additional continuation request.  If a client instance does so, the
AS MUST return an "invalid_continuation" error (response-error).
Paragraph (version A):
Since the interaction reference is a one-time-use value as described
in interaction-callback, if the client instance needs to make
additional continuation calls after this request, the client instance
MUST NOT include the interaction reference.  If the AS detects a
client instance submitting the same interaction reference multiple
times, the AS MUST return a "too_many_attempts" error (response-
error) and SHOULD invalidate the ongoing request.
Paragraph (version B):
state.
Paragraph (version A):
The client instance might need to modify an ongoing request, whether
or not tokens have already been issued or claims have already been
released.  In such cases, the client instance makes an HTTP PATCH
request to the continuation URI and includes any fields it needs to
modify.  Fields that aren't included in the request are considered
unchanged from the original request.
Paragraph (version A):
state and re-evaluate the authorization in the new context created by
the update request.
Paragraph (version B):
The client instance might need to modify an ongoing request, whether
or not tokens have already been issued or subject information has
already been released.  In such cases, the client instance makes an
HTTP PATCH request to the continuation URI and includes any fields it
needs to modify.  Fields that aren't included in the request are
considered unchanged from the original request.
Paragraph (version B):
state and re-evaluate the authorization in the new context created by
the update request, since the extent and context of the request could
have changed.
Paragraph (version A):
The client instance MAY include the "access_token" and "subject"
fields as described in request-token and request-subject.  Inclusion
of these fields override any values in the initial request, which MAY
trigger additional requirements and policies by the AS.  For example,
if the client instance is asking for more access, the AS could
require additional interaction with the RO to gather additional
consent.  If the client instance is asking for more limited access,
the AS could determine that sufficient authorization has been granted
to the client instance and return the more limited access rights
immediately.
Paragraph (version B):
state, the AS could decide to remember the larger scale of access
rights associated with the grant request, allowing the client
instance to make subsequent requests of different subsets of granted
access.  The details of this are out of scope for this specification.
Paragraph (version A):
The client instance MAY include the "user" field as described in
request-user to present new assertions or information about the end
user.  The AS SHOULD check that this presented user information is
consistent with any user information previously presented by the
client instance for this grant request.
Paragraph (version A):
The client instance MUST NOT include the "client" section of the
request, since the client instance is assumed not to have changed.
Paragraph (version B):
The client instance MAY include the "user" field as described in
request-user to present new assertions or information about the end
user.  The AS SHOULD check that this presented user information is
consistent with any user information previously presented by the
client instance or otherwise associated with this grant request.
Paragraph (version B):
The client instance MUST NOT include the "client" section of the
request, since the client instance is assumed not to have changed.
Modification of client instance information, including rotation of
keys associated with the client instance, is outside the scope of
this specification.
Paragraph (version A):
If the modified request can be granted immediately by the AS, the
response MAY contain any newly-created response-token or newly-
released response-subject.  The response MAY contain a new response-
continue as described above.  If interaction can occur, the response
SHOULD contain response-interact as well.
Paragraph (version B):
state), the response MAY contain any newly-created response-token or
newly-released response-subject.  The response MAY contain a new
response-continue as described above.  If interaction can occur, the
response SHOULD contain response-interact as well.
Paragraph (version A):
The AS replaces the previous "access" from the first request,
allowing the AS to determine if any previously-granted consent
already applies.  In this case, the AS would likely determine that
reducing the breadth of the requested access means that new access
tokens can be issued to the client instance.  The AS would likely
revoke previously-issued access tokens that had the greater access
rights associated with them, unless they had been issued with the
"durable" flag.
Paragraph (version B):
The AS replaces the previous "access" from the first request,
allowing the AS to determine if any previously-granted consent
already applies.  In this case, the AS would determine that reducing
the breadth of the requested access means that new access tokens can
be issued to the client instance without additional interaction or
consent.  The AS would likely revoke previously-issued access tokens
that had the greater access rights associated with them, unless they
had been issued with the "durable" flag.
Paragraph (version A):
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):
If the token is sender-constrained (i.e., not a bearer token), it
MUST be sent use-access-token.
Paragraph (version A):
If the token is a bearer token, the client instance MUST present
proof of the same request-client as described in binding-keys.
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 the rotate and revoke actions
defined in the following sections.  Other actions are undefined by
this specification.
Paragraph (version B):
If the token is sender-constrained (i.e., not a bearer token), it
MUST be sent use-access-token based on the key bound to the access
token.
Paragraph (version B):
If the token is a bearer token, the client instance MUST present
proof of the request-client (or its most recent rotation) as
described in binding-keys.  Note that this is usually the same key
used in the initial grant request.
Paragraph (version A):
If the client instance has an access token and that access token
expires, the client instance might want to rotate the access token.
Rotating an access token consists of issuing a new access token in
place of an existing access token, with the same rights and
properties as the original token, apart from an updated expiration
time.
Paragraph (version A):
To rotate an access token, the client instance makes an HTTP POST to
the token management URI, sending the access token in the appropriate
header and signing the request with the appropriate key.
Paragraph (version A):
Note that in many cases, the access token will have expired for
regular use.  To facilitate token rotation, the AS SHOULD honor the
rotation request of the expired access token since it is likely that
the client instance is attempting to refresh the expired token.  To
support this, the AS MAY allow a longer lifetime for token management
compared to its use at an RS.  An AS MUST NOT honor a rotation
request for an access token that has been revoked or otherwise
disabled.
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
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
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):
The access rights in the "access" array for the rotated access token
MUST be included in the response and MUST be the same as the token
before rotation.  If the client instance requires different access
rights, the client instance can request a new access token by
creating request or by continue-modify.
Paragraph (version B):
If the client instance has an access token and that access token
expires, the client instance might want to rotate the access token to
a new value without expiration.  Rotating an access token consists of
issuing a new access token in place of an existing access token, with
the same rights and properties as the original token, apart from an
updated token value and expiration time.
Paragraph (version B):
To rotate an access token, the client instance makes an HTTP POST to
the token management URI with no message body, sending the access
token in the appropriate header and signing the request with the
appropriate key.
Paragraph (version B):
The client instance can not request to alter the access rights
associated with the access token during a rotation request.  To get
an access token with different access rights for this grant request,
the client instance has to call the continue-modify functionality to
get a new access token.  The client instance can also create a new
grant request with the required access rights.
Paragraph (version B):
Note that in many cases, the access token will have expired for
regular use at an RS.  To facilitate token rotation, the AS SHOULD
honor the rotation request of the expired access token since it is
likely that the client instance is attempting to refresh the expired
token.  To support this, the AS MAY allow a longer lifetime for token
management compared to its use at an RS.  An AS MUST NOT honor a
rotation request for an access token that has been explicitly revoked
or otherwise disabled.
Paragraph (version B):
If the token is validated and the key is appropriate for the request,
the AS MUST invalidate the current access token value 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 B):
For successful rotations, 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 B):
The access rights in the "access" array for the rotated access token
MUST be included in the response and MUST be the same as the token
before rotation.
Paragraph (version A):
When an access token is used with a key proof, this is a bound
token request.  This type of request is used for calls to the RS
as well as the AS during negotiation.
Paragraph (version A):
When a key proof is used with no access token, this is a non-
authorized signed request.  This type of request is used for calls
to the AS to initiate a negotiation.
Paragraph (version B):
When an access token is used with a key proof, this is a bound
token request.  This type of request is used for calls to the RS
as well as the AS during grant negotiation.
Paragraph (version B):
When a key proof is used with no access token, this is a non-
authorized signed request.  This type of request is used for calls
to the AS to initiate a grant negotiation.
Paragraph (version A):
Several different places in GNAP require the presentation of key
material by value.  Proof of this key material MUST be bound to a
request, the nature of which varies with the location in the protocol
the key is used.  For a key used as part of a client instance's
initial request in request-client, the key value is the client
instance's public key, and proof of that key MUST be presented in
that request.  For a key used as part of an access token response in
response-token-single, the proof of that key MUST be used when
presenting the access token.
Paragraph (version B):
Several different places in GNAP require the presentation of key
material by value or by reference.  Key material sent by value is
sent using a JSON object with several fields described in this
section.
Paragraph (version B):
All keys are associated with a specific key proofing method.  The
proofing method associated with the key is indicated using the
"proof" field of the key object.
Paragraph (version A):
Keys in GNAP can also be passed by reference such that the party
receiving the reference will be able to determine the appropriate
keying material for use in that part of the protocol.
Paragraph (version B):
When the key is presented in GNAP, proof of this key material MUST be
used to bind the request, the nature of which varies with the
location in the protocol the key is used.  For a key used as part of
a client instance's initial request in request-client, the key value
represents the client instance's public key, and proof of that key
MUST be presented in that request.  For a key used as part of an
access token response in response-token-single, the proof of that key
MUST be used when the client instance later presents the access token
to the RS.
Paragraph (version B):
Keys in GNAP can also be passed by reference such that the party
receiving the reference will be able to determine the appropriate
keying material for use in that part of the protocol.  Key references
are a single opaque string.
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 URI.  For interoperability, this method
could later be described as an extension.
Paragraph (version B):
The means of dereferencing this reference to a key value and proofing
mechanism are out of scope for this specification.  Commonly, key
references are created by the AS and are not necessarily needed to be
understood 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 AS, which could be
accomplished by a client publishing a public key at a URI, for
example.  For interoperability, this method could later be described
as an extension, but doing so is out of scope for this specification.
Paragraph (version A):
The method the client instance uses to send an access token depends
on whether the token is bound to a key, and if so which proofing
method is associated with the key.  This information is conveyed by
the "key" parameter and the "bearer" flag in response-token-single
and response-token-multiple responses.
Paragraph (version B):
Access tokens are issued to client instances in GNAP to allow the
client instance to make an authorized call to an API.  The method the
client instance uses to send an access token depends on whether the
token is bound to a key, and if so which proofing method is
associated with the key.  This information is conveyed by the "key"
parameter and the "bearer" flag in response-token-single.
Paragraph (version A):
The "Form-Encoded Body Parameter" and "URI Query Parameter" methods
of RFC6750 MUST NOT be used.
Paragraph (version A):
The client software MUST reject as an "invalid_flag" error a
situation where the "flags" field contains the "bearer" flag and the
"key" field is present with any value.
Paragraph (version B):
The "Form-Encoded Body Parameter" and "URI Query Parameter" methods
of RFC6750 MUST NOT be used for GNAP access tokens.
Paragraph (version A):
This is explicitly defined as the signature algorithm specified by
the associated key material and the content digest is calculated
using sha-256.
Paragraph (version A):
The key binding methods in this section MAY be used by other
components making calls as part of GNAP, such as the extensions
allowing the RS to make calls to the AS defined in I-D.ietf-gnap-
resource-servers.  To facilitate this extended use, the sections
below are defined in generic terms of the "signer" and "verifier" of
the HTTP message.  In the core functions of GNAP, the "signer" is the
client instance and the "verifier" is the AS or RS, as appropriate.
Paragraph (version B):
The key binding methods in this section MAY be used by other
components making calls as part of GNAP, such as the extensions
allowing the RS to make calls to the AS defined in I-D.ietf-gnap-
resource-servers.  To facilitate this extended use, the sections
below are defined in generic terms of the "signer" and "verifier" of
the HTTP message.  In the core functions of GNAP specified in this
document, the "signer" is the client instance and the "verifier" is
the AS (for grant requests) or RS (for resource requests), as
appropriate.
Paragraph (version A):
When used for delegation in GNAP, these key binding mechanisms allow
the AS to ensure that the keys presented by the client instance in
the initial request are in control of the party calling any follow-up
or continuation requests.  To facilitate this requirement, the
response-continue includes an access token bound to the request-
client, and that key (or its most recent rotation) MUST be proved in
all continuation requests continue-request.  Token management
requests (token-management) are similarly bound to either the access
token's own key or, in the case of bearer tokens, the client
instance's key.
Paragraph (version B):
When used for delegation in GNAP, these key binding mechanisms allow
the AS to ensure that the keys presented by the client instance in
the initial request are in control of the party calling any follow-up
or continuation requests.  To facilitate this requirement, the
response-continue includes an access token bound to the request-
client, and that key (or its most recent rotation) MUST be proved in
all continuation requests (continue-request).  Token management
requests (token-management) are similarly bound to either the access
token's own key or, in the case of bearer tokens, the client
instance's key.
Paragraph (version A):
If the signer's key presented is a JWK, the "keyid" parameter of the
signature MUST be set to the "kid" value of the JWK, the signing
algorithm used MUST be the JWS algorithm denoted by the key's "alg"
field, and the explicit "alg" signature parameter MUST NOT be
included.
Paragraph (version B):
If the signer's key presented is a JWK, the "keyid" parameter of the
signature MUST be set to the "kid" value of the JWK, the signing
algorithm used MUST be the JWS algorithm denoted by the key's "alg"
field of the JWK.
Paragraph (version B):
The explicit "alg" signature parameter MUST NOT be included in the
signature, since the algorithm will be derived either from the key
material or from the "proof" value.
Paragraph (version A):
If the HTTP Message includes a message body, the verifier MUST
calculate and verify the value of the "Digest" or "Content-Digest"
header.  The verifier MUST ensure that the signature covers all
required message components.  The verifier MUST validate the
signature against the expected key of the signer.
Paragraph (version A):
When rotating a key using HTTP Message Signatures, the message, which
includes the new public key value or reference, is first signed with
the old key.  The message is then signed again with the new key,
including the signature from the old key under the signature of the
new key.
Paragraph (version B):
The verifier MUST ensure that the signature covers all required
message components.  If the HTTP Message includes a message body, the
verifier MUST calculate and verify the value of the "Content-Digest"
header.  The verifier MUST validate the signature against the
expected key of the signer.
Paragraph (version B):
When rotating a key using HTTP Message Signatures, the message, which
includes the new public key value or reference, is first signed with
the old key.  The message is then signed again with the new key by
including the signature from the old key under the signature of the
new key.
Paragraph (version A):
When the verifier receives the Detached-JWS header, it MUST parse and
validate the JWS object.  The signature MUST be validated against the
expected key of the signer.  All required fields MUST be present and
their values MUST be valid.  If the HTTP message request contains a
body, the verifier MUST calculate the hash of body just as the signer
does, with no normalization or transformation of the request.
Paragraph (version B):
When the verifier receives the Detached-JWS header, it MUST parse and
validate the JWS object.  The signature MUST be validated against the
expected key of the signer.  If the HTTP message request contains a
body, the verifier MUST calculate the hash of body just as the signer
does, with no normalization or transformation of the request.  All
required fields MUST be present and their values MUST be valid.  All
fields MUST match the corresponding portions of the HTTP message.
For example, the "htm" field of the JWS header has to be the same as
the HTTP verb used in the request.
Paragraph (version A):
Note that this proof method depends on a specific cryptographic
algorithm, SHA-256, in two ways: the "ath" hash algorithm is
hardcoded, and computing the payload of the detached/attached
signature also uses a hardcoded hash.  A future version of this
document may address crypto-agility for both these uses by replacing
ath with a new header that upgrades the algorithm, and possibly
defining a new header that indicates the HTTP content's hash method.
Paragraph (version A):
When rotating a key using Detached JWS, the message, which includes
the new public key value or reference, is first signed with the old
key using a JWS object with "typ" header value "gnap-binding-
rotation+jwsd".  The value of the JWS object is then taken as the
payload of a new JWS object, to be signed by the new key.
Paragraph (version B):
Note that this proof method depends on a specific cryptographic
algorithm, SHA-256, in two ways: the "ath" hash algorithm is
hardcoded, and computing the payload of the detached/attached
signature also uses a hardcoded hash.  A future version of this
document may address crypto-agility for both these uses by replacing
ath with a new header that upgrades the algorithm, and possibly
defining a new JWS header that indicates the HTTP content's hash
method.
Paragraph (version B):
When rotating a key using Detached JWS, the message, which includes
the new public key value or reference, is first signed with the old
key as described above using a JWS object with "typ" header value
"gnap-binding-rotation+jwsd".  The value of the JWS object is then
taken as the payload of a new JWS object, to be signed by the new key
using the parameters above.
Paragraph (version B):
The value of the new JWS object is sent in the Detached-JWS header.
Paragraph (version A):
When the verifier receives an attached JWS request, it MUST parse and
validate the JWS object.  The signature MUST be validated against the
expected key of the signer.  All required fields MUST be present and
their values MUST be valid.  If the HTTP message request contains a
body, the verifier MUST decode the payload of the JWS object and
treat this as the HTTP message body.
Paragraph (version B):
When the verifier receives an attached JWS request, it MUST parse and
validate the JWS object.  The signature MUST be validated against the
expected key of the signer.  All required fields MUST be present and
their values MUST be valid.  All fields MUST match the corresponding
portions of the HTTP message.  For example, the "htm" field of the
JWS header has to be the same as the HTTP verb used in the request.
Paragraph (version A):
The root of this structure is a JSON array.  The elements of the JSON
array represent rights of access that are associated with the the
access token.  The resulting access is the union of all elements
within the array.
Paragraph (version B):
The root of this structure is a JSON array.  The elements of the JSON
array represent rights of access that are associated with the the
access token.  Individual rights of access can be defined by the RS
as either an object or a string.  The resulting access is the union
of all elements within the array.
Paragraph (version A):
While it is expected that many APIs will have their own properties, a
set of common properties are defined here.  Specific API
implementations SHOULD NOT re-use these fields with different
semantics or syntax.  The available values for these properties are
determined by the API being protected at the RS.  All values are
OPTIONAL at the discretion of the API definition.
Paragraph (version A):
The access requested for a given object when using these fields is
the cross-product of all fields of the object.  That is to say, the
object represents a request for all "actions" listed to be used at
all "locations" listed for all possible "datatypes" listed within the
object.  Assuming the request above was granted, the client instance
could assume that it would be able to do a "read" action against the
"images" on the first server as well as a "delete" action on the
"metadata" of the second server, or any other combination of these
fields, using the same access token.
Paragraph (version B):
While it is expected that many APIs will have their own properties, a
set of common properties are defined here.  Specific API
implementations SHOULD re-use these fields with the same semantics
and syntax.  The available values for these properties are determined
by the API being protected at the RS.  This specification does not
require the use of any of these common fields by an API definition,
but instead provides them as reusable generic components for API
designers to make use of.  The allowable values of all fields are
determined by the API being protected, as defined by a particular
"type" value.
Paragraph (version B):
The access requested for each object in the array is the cross-
product of all fields of the object.  That is to say, the object
represents a request for all "actions" listed to be used at all
"locations" listed for all possible "datatypes" listed within the
object.  Assuming the request above was granted, the client instance
could assume that it would be able to do a "read" action against the
"images" on the first server as well as a "delete" action on the
"metadata" of the second server, or any other combination of these
fields, using the same access token.
Paragraph (version A):
To request a different combination of access, such as requesting one
of the possible "actions" against one of the possible "locations" and
a different choice of possible "actions" against a different one of
the possible "locations", the client instance can include multiple
separate objects in the "resources" array.  The following non-
normative example uses the same fictitious "photo-api" type
definition to request a single access token with more specifically
targeted access rights by using two discrete objects within the
request.
Paragraph (version B):
To request a different combination of access, such as requesting one
of the possible "actions" against one of the possible "locations" and
a different choice of possible "actions" against a different one of
the possible "locations", the client instance can include multiple
separate objects in the "resources" array.  The total access rights
for the resulting access token is the union of all objects.  The
following non-normative example uses the same fictitious "photo-api"
type definition to request a single access token with more
specifically targeted access rights by using two discrete objects
within the request.
Paragraph (version A):
By design, the protocol minimizes the need for any pre-flight
discovery.  To begin a request, the client instance only needs to
know the endpoint of the AS and which keys it will use to sign the
request.  Everything else can be negotiated dynamically in the course
of the protocol.
Paragraph (version B):
By design, GNAP minimizes the need for any pre-flight discovery.  To
begin a request, the client instance only needs to know the grant
endpoint of the AS (a single URI) and which keys it will use to sign
the request.  Everything else can be negotiated dynamically in the
course of the protocol.
Paragraph (version A):
Security considerations, especially related to the potential of a
[compromised RS]{#security-compromised-rs} redirecting the requests
of an otherwise properly authenticated client, need to be carefully
considered when allowing such a discovery process.  This risk can be
mitigated by an alternative pre-registration process so that the
client knows which AS protects which RS.
Paragraph (version B):
Security considerations, especially related to the potential of a
security-compromised-rs redirecting the requests of an otherwise
properly authenticated client, need to be carefully considered when
allowing such a discovery process.  This risk can be mitigated by an
alternative pre-registration process so that the client knows which
AS protects which RS.  There are also privacy considerations related
to revealing which AS is protecting a given resource, discussed in
privacy-correlation-client.
Paragraph (version A):
IANA is requested to create XX registries for the Grant Negotiation
and Authorization Protocol and to populate those registries with
initial values as described in this section.
Paragraph (version A):
All use of value typing is based on RFC8259 data types and MUST be
one of the following: number, object, string, boolean, or array.
When the type is array, the contents of the array MUST be specified,
as in "array of objects".  If a parameter is available in different
types, each type SHOULD be registered separately.
Paragraph (version B):
IANA is requested to create 16 registries for the Grant Negotiation
and Authorization Protocol and to populate those registries with
initial values as described in this section.
Paragraph (version B):
All use of value typing is based on RFC8259 data types and MUST be
one of the following: number, object, string, boolean, or array.
When the type is array, the contents of the array MUST be specified,
as in "array of objects".  When the type is object, the structure of
the object MUST be specified in the definition.  If a parameter is
available in different types, each type SHOULD be registered
separately.
Paragraph (version A):
Even more importantly, the client instance proving possession of a
key on the first request allows the AS to associate future requests
with each other.  The access token used for grant continuation is
bound to the same key and proofing mechanism used by the client
instance in its initial request, which means that the client instance
needs to prove possession of that same key in future requests
allowing the AS to be sure that the same client instance is executing
the follow-ups for a given ongoing grant request.  Therefore, the AS
has to ensure that all subsequent requests for a grant are associated
with the same key that started the grant, or the most recent rotation
of that key.  This need holds true even if the initial key is
previously unknown to the AS, such as would be the case when a client
instance creates an ephemeral key for its request.  Without this
ongoing association, an attacker would be able to impersonate a
client instance in the midst of a grant request, potentially stealing
access tokens and subject information with impunity.
Paragraph (version B):
Even more importantly, the client instance proving possession of a
key on the first request allows the AS to associate future requests
with each other by binding all future requests in that transaction to
the same key.  The access token used for grant continuation is bound
to the same key and proofing mechanism used by the client instance in
its initial request, which means that the client instance needs to
prove possession of that same key in future requests allowing the AS
to be sure that the same client instance is executing the follow-ups
for a given ongoing grant request.  Therefore, the AS has to ensure
that all subsequent requests for a grant are associated with the same
key that started the grant, or the most recent rotation of that key.
This need holds true even if the initial key is previously unknown to
the AS, such as would be the case when a client instance creates an
ephemeral key for its request.  Without this ongoing association, an
attacker would be able to impersonate a client instance in the midst
of a grant request, potentially stealing access tokens and subject
information with impunity.
Paragraph (version A):
Additionally, all access tokens in GNAP default to be associated with
the key that was presented during the grant request that created the
access token.  This association allows an RS to know that the
presenter of the access token is the same party that the token was
issued to, as identified by their keys.  While non-bound bearer
tokens are an option in GNAP, these types of tokens have their own
tradeoffs discussed elsewhere in this section.
Paragraph (version B):
Additionally, all access tokens in GNAP default to be associated with
the key that was presented during the grant request that created the
access token.  This association allows an RS to know that the
presenter of the access token is the same party that the token was
issued to, as identified by their keys.  While non-bound bearer
tokens are an option in GNAP, these types of tokens have their own
tradeoffs discussed in security-bearer-tokens.
Paragraph (version A):
Client instances are identified by their unique keys, and anyone with
access to a client instance's key material will be able to
impersonate that client instance to all parties.  This is true for
both calls to the AS as well as calls to an RS using a key-bound
access token.
Paragraph (version A):
Different types of client software have different methods available
for creating, managing, and registering keys.  GNAP explicitly allows
for ephemeral clients, such as SPAs, and single-user clients, such as
mobile applications, to create and present their own keys during the
initial grant request.  The client software can securely generate a
keypair on-device and present the public key, along with proof of
holding that public key, to the AS as part of the initial request.
To facilitate trust in these ephemeral keys, GNAP further allows for
an extensible set of client information to be passed with the
request.  This information can include device posture and third-party
attestations of the client software's provenance and authenticity,
depending on the needs and capabilities of the client software and
its deployment.
Paragraph (version B):
Client instances are identified by their unique keys, and anyone with
access to a client instance's key material will be able to
impersonate that client instance to all parties.  This is true for
both calls to the AS as well as calls to an RS using an access token
bound to the client instance's unique key.  As a consequence, it is
of utmost importance for a client instance to protect its private key
material.
Paragraph (version B):
Different types of client software have different methods for
creating, managing, and registering keys.  GNAP explicitly allows for
ephemeral clients (such as SPAs) and single-user clients (such as
mobile applications) to create and present their own keys during the
initial grant request without any explicit pre-registration step.
The client software can securely generate a keypair on-device and
present the public key, along with proof of holding the associated
private key, to the AS as part of the initial request.  To facilitate
trust in these ephemeral keys, GNAP further allows for an extensible
set of client information to be passed with the request.  This
information can include device posture and third-party attestations
of the client software's provenance and authenticity, depending on
the needs and capabilities of the client software and its deployment.
Paragraph (version A):
Consequently, protecting, monitoring, and auditing the AS is
paramount to preserving the security of a GNAP-protected ecosystem.
Paragraph (version A):
The cryptographic methods used by GNAP for key-proofing can support
both asymmetric and symmetric cryptography, and can be extended to
use a wide variety of mechanisms.  Implementers will find useful the
available guidelines on cryptographic key management provided in
RFC4107.  While symmetric cryptographic systems have some benefits in
speed and simplicity, they have a distinct drawback that both parties
need access to the same key in order to do both signing and
verification of the message.  This means that when the client
instance calls the AS to request a token, the AS needs to know the
exact value of the client instance's key (or be able to derive it) in
order to validate the key proof signature.  With asymmetric keys, the
client needs only to send its public key to the AS to allow for
verification that the client holds the associated private key,
regardless of whether that key was pre-registered or not with the AS.
Paragraph (version B):
Consequently, protecting, monitoring, and auditing the AS is
paramount to preserving the security of a GNAP-protected ecosystem.
The AS presents attackers with a valuable target for attack.
Fortunately, the core focus and function of the AS is to provide
security for the ecosystem, unlike the RS whose focus is to provide
an API or the client software whose focus is to access the API.
Paragraph (version B):
Many of the cryptographic methods used by GNAP for key-proofing can
support both asymmetric and symmetric cryptography, and can be
extended to use a wide variety of mechanisms.  Implementers will find
useful the available guidelines on cryptographic key management
provided in RFC4107.  While symmetric cryptographic systems have some
benefits in speed and simplicity, they have a distinct drawback that
both parties need access to the same key in order to do both signing
and verification of the message.  This means that when the client
instance calls the AS to request a token, the AS needs to know the
exact value of the client instance's key (or be able to derive it) in
order to validate the key proof signature.  With asymmetric keys, the
client needs only to send its public key to the AS to allow for
verification that the client holds the associated private key,
regardless of whether that key was pre-registered or not with the AS.
Paragraph (version A):
signature.  With asymmetric cryptography, the RS only needs to know
the public key associated with the token in order to validate, and
therefore cannot create any new calls.
Paragraph (version B):
signature using the shared key.  With asymmetric cryptography, the RS
needs to know only the public key associated with the token in order
to validate the request, and therefore the RS cannot create any new
signed calls.
Paragraph (version A):
While both signing approaches are allowed, GNAP treats these two
classes of keys somewhat differently.  Only the public portion of
asymmetric keys are allowed to be sent by value in requests to the AS
when establishing a connection.  Since sending a symmetric key (or
the private portion of an asymmetric key) would expose the signing
material to any parties on the request path, including any attackers,
sending these kinds of keys is prohibited.  Symmetric keys can still
be used by client instances, but only a reference to the key and not
its value can be sent.  This allows the AS to use pre-registered
symmetric keys as well as key derivation schemes to take advantage of
symmetric cryptography but without requiring key distribution at
runtime, which would expose the keys in transit.
Paragraph (version B):
While both signing approaches are allowed, GNAP treats these two
classes of keys somewhat differently.  Only the public portion of
asymmetric keys are allowed to be sent by value in requests to the AS
when establishing a connection.  Since sending a symmetric key (or
the private portion of an asymmetric key) would expose the signing
material to any parties on the request path, including any attackers,
sending these kinds of keys by value is prohibited.  Symmetric keys
can still be used by client instances, but only if the client
instance can send a reference to the key and not its value.  This
approach allows the AS to use pre-registered symmetric keys as well
as key derivation schemes to take advantage of symmetric cryptography
but without requiring key distribution at runtime, which would expose
the keys in transit.
Paragraph (version A):
Bearer access tokens can be used by any party that has access to the
token itself, without any additional information.  As a natural
consequence, any RS that a bearer token is presented to has the
technical capability of presenting that bearer token to another RS,
as long as the token is valid.  It also means that any party that is
able capture of the token value in storage or in transit is able to
use the access token.  While bearer tokens are inherently simpler,
this simplicity has been misapplied and abused in making needlessly
insecure systems.
Paragraph (version A):
In GNAP, key-bound access tokens are the default due to their higher
security properties.  While bearer tokens can be used in GNAP, their
use should be limited to cases where the simplicity benefits outweigh
the significant security downsides.
Paragraph (version B):
Bearer access tokens can be used by any party that has access to the
token itself, without any additional information.  As a natural
consequence, any RS that a bearer token is presented to has the
technical capability of presenting that bearer token to another RS,
as long as the token is valid.  It also means that any party that is
able capture of the token value in storage or in transit is able to
use the access token.  While bearer tokens are inherently simpler,
this simplicity has been misapplied and abused in making needlessly
insecure systems.  The downsides of bearer tokens have become more
pertinent lately as stronger authentication systems have caused some
attacks to shift to target tokens and APIs.
Paragraph (version B):
In GNAP, key-bound access tokens are the default due to their higher
security properties.  While bearer tokens can be used in GNAP, their
use should be limited to cases where the simplicity benefits outweigh
the significant security downsides.  One common deployment pattern is
to use a gateway that takes in key-bound tokens on the outside, and
verifies the signatures on the incoming requests, but translates the
requests to a bearer token for use by trusted internal systems.  The
bearer tokens are never issued or available outside of the internal
systems, greatly limiting the exposure of the less secure tokens but
allowing the internal deployment to benefit from the advantages of
bearer tokens.
Paragraph (version A):
Key-bound access tokens, as the name suggests, are bound to a
specific key and must be presented along with proof of that key
during use.  The key itself is not presented at the same time as the
token, so even if a token value is captured, it cannot be used to
make a new request.  This is particularly true for an RS, which will
see the token value but will not see the keys used to make the
request.
Paragraph (version B):
Key-bound access tokens, as the name suggests, are bound to a
specific key and must be presented along with proof of that key
during use.  The key itself is not presented at the same time as the
token, so even if a token value is captured, it cannot be used to
make a new request.  This is particularly true for an RS, which will
see the token value but will not see the keys used to make the
request (assuming asymmetric cryptography is in use, see security-
symmetric).
Paragraph (version A):
Some key-bound tokens are susceptible to replay attacks, depending on
the details of the signing method used.  If a signature method covers
only portions of a given request, that same signature proof can be
used by an attacker to make a similar call, potentially even varying
elements that are outside of the protection of the signature.  Key
proofing mechanisms used with access tokens therefore need to use
replay protection mechanisms covered under the signature such as a
per-message nonce, a reasonably short time validity window, or other
uniqueness constraints.  The details of using these will vary
depending on the key proofing mechanism in use, but for example, HTTP
Message Signatures has both a "created" and "nonce" signature
parameter as well as the ability to cover significant portions of the
HTTP message.
Paragraph (version B):
Some key-bound tokens are susceptible to replay attacks, depending on
the details of the signing method used.  Key proofing mechanisms used
with access tokens therefore need to use replay protection mechanisms
covered under the signature such as a per-message nonce, a reasonably
short time validity window, or other uniqueness constraints.  The
details of using these will vary depending on the key proofing
mechanism in use, but for example, HTTP Message Signatures has both a
"created" and "nonce" signature parameter as well as the ability to
cover significant portions of the HTTP message.  All of these can be
used to limit the attack surface.
Paragraph (version A):
If a client instance is able to work with multiple AS's
simultaneously, it is more possible for an attacker to add a
compromised AS to the client instance's configuration and cause the
client software to start a request at the compromised AS.  This AS
could then proxy the client's request to a valid AS in order to
attempt to get the resource owner to approve access for the
legitimate client instance.
Paragraph (version A):
A client instance needs to always be aware of which AS it is talking
to throughout a grant process, and ensure that any callback for one
AS does not get conflated with the callback to different AS.  The
interaction finish hash calculate allows a client instance to protect
against this kind of substitution, but only if the client instance
validates the hash.  If the client instance does not use an
interaction finish method or does not check the interaction finish
hash value, the compromised AS can be granted a valid access token on
behalf of the resource owner.  See AXELAND2021 for details of one
such attack, which has been since addressed in this document by
including the grant endpoint in the interaction hash calculation.
The client instance still needs to validate the hash for the attack
to be prevented.
Paragraph (version B):
If a client instance is able to work with multiple AS's
simultaneously, it is possible for an attacker to add a compromised
AS to the client instance's configuration and cause the client
software to start a request at the compromised AS.  This AS could
then proxy the client's request to a valid AS in order to attempt to
get the resource owner to approve access for the legitimate client
instance.
Paragraph (version B):
A client instance needs to always be aware of which AS it is talking
to throughout a grant process, and ensure that any callback for one
AS does not get conflated with the callback to different AS.  The
interaction finish hash calculation in interaction-hash allows a
client instance to protect against this kind of substitution, but
only if the client instance validates the hash.  If the client
instance does not use an interaction finish method or does not check
the interaction finish hash value, the compromised AS can be granted
a valid access token on behalf of the resource owner.  See
AXELAND2021 for details of one such attack, which has been since
addressed in this document by including the grant endpoint in the
interaction hash calculation.  Note that the client instance still
needs to validate the hash for the attack to be prevented.
Paragraph (version A):
In cases where the AS trusts the client software more completely, due
to policy or by previous approval of a given client instance, the AS
can take this user information as a statement that the user is
present and could issue access tokens and release subject information
without interaction.  The AS should only take such action in very
limited circumstances, as a client instance could assert whatever it
likes for the user's identifiers in its request.
Paragraph (version B):
In cases where the AS trusts the client software more completely, due
to policy or by previous approval of a given client instance, the AS
can take this user information as a statement that the user is
present and could issue access tokens and release subject information
without interaction.  The AS should only take such action in very
limited circumstances, as a client instance could assert whatever it
likes for the user's identifiers in its request.  The AS can limit
the possibility of this by issuing randomized opaque identifiers to
client instances to represent different end user accounts after an
initial login.
Paragraph (version A):
An AS can also provide warnings and caveats to resource owners during
the authorization process, allowing the user to make an informed
decision regarding the software they are authorizing.  For example,
if the AS has done vetting of the client software and this specific
instance, it can present a different authorization screen compared to
a client instance that is presenting all of its information at
runtime.
Paragraph (version B):
Finally, an AS can use platform attestations and other signals from
the client instance at runtime to determine whether the software
making the request is legitimate or not.  The details of such
attestations are outside the scope of the core protocol, but the
"client" portion of a grant request provides a natural extension
point to such information.
Paragraph (version A):
An AS can also warn the resource owner about the provenance of the
information it is displaying, allowing the resource owner to make a
more informed delegation decision.  For example, an AS can visually
differentiate between a client instance that can be traced back to a
specific developer's registration and an instance that has self-
asserted its own key and display information.
Paragraph (version B):
An AS can also warn the resource owner about the provenance of the
information it is displaying, allowing the resource owner to make a
more informed delegation decision.  For example, an AS can visually
differentiate between a client instance that can be traced back to a
specific developer's registration and an instance that has self-
asserted its own display information.
Paragraph (version A):
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 A):
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):
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 and values not passed in the URI.  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.  An AS
implementation can avoid this problem by creating URIs using
unguessable values that are randomized for each new grant request.
Paragraph (version A):
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 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 in 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 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 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 Referer header.
Paragraph (version A):
signature to the "Client-Cert" header field using I-D.ietf-httpbis-
message-signatures.  This signature would be effectively ignored by
GNAP but understood by the downstream service as part of its
deployment.
Paragraph (version B):
signature to the Client-Cert header field using I-D.ietf-httpbis-
message-signatures.  This signature would be effectively ignored by
GNAP (since it would not use GNAP's "tag" parameter value) but would
be understood by the downstream service as part of its deployment.
Paragraph (version A):
MTLS in GNAP need not use a PKI backing, as self-signed certificates
and certificates from untrusted authorities can still be presented as
part of a TLS connection.  In this case, the verifier would validate
the connection but accept whatever certificate was presented by the
client software.  This specific certificate would then be bound to
all future connections from that client software by being bound to
the resulting access tokens.  See security-mtls for more
considerations on MTLS as a key proofing mechanism.
Paragraph (version B):
MTLS in GNAP need not use a PKI backing, as self-signed certificates
and certificates from untrusted authorities can still be presented as
part of a TLS connection.  In this case, the verifier would validate
the connection but accept whatever certificate was presented by the
client software.  This specific certificate would then be bound to
all future connections from that client software by being bound to
the resulting access tokens, in a trust-on-first-use pattern.  See
security-mtls for more considerations on MTLS as a key proofing
mechanism.
Paragraph (version A):
The keys for client instances could be distributed as part of the
deployment process of instances of the client software.  For example,
an application installation framework could generate a keypair for
each copy of client software, then both install it into the client
software upon installation and registering that instance with the AS.
Paragraph (version A):
Additionally, it's possible for the AS to generate keys to be used
with access tokens that are separate from the keys used by the client
instance to request tokens.  In this method, the AS would generate
the asymmetric keypair or symmetric key and return the entire key,
including all private signing information, to the client instance
alongside the access token itself.  This approach would make
interception of the return from the token endpoint equivalent to that
of a bearer token, since all information required to use the access
token would be present in the request.
Paragraph (version B):
GNAP does not define ways for the client instances keys to be
provided to the client instances, particularly in light of how those
keys are made known to the AS.  These keys could be generated
dynamically on the client software or pre-registered at the AS in a
static developer portal.  The keys for client instances could also be
distributed as part of the deployment process of instances of the
client software.  For example, an application installation framework
could generate a keypair for each copy of client software, then both
install it into the client software upon installation and registering
that instance with the AS.
Paragraph (version B):
Alternatively, it's possible for the AS to generate keys to be used
with access tokens that are separate from the keys used by the client
instance to request tokens.  In this method, the AS would generate
the asymmetric keypair or symmetric key and return the public key or
key reference, to the client instance alongside the access token
itself.  The means for the AS to return generated key values to the
client instance are out of scope, since GNAP does not allow the
transmission of private or shared key information within the protocol
itself.
Paragraph (version B):
Additionally, if the token is bound to a key other than the client
instance's presented key, this opens a possible attack surface for an
attacker's AS to request an access token then substitute their own
key material in the response to the client instance.  The attacker's
AS would need to be able to use the same key as the client instance,
but this setup would allow an attacker's AS to make use of a
compromised key within a system.  This attack can be prevented by
only binding access tokens to the client instance's presented keys,
and by having client instances have a strong association between
which keys they expect to use and the AS they expect to use them on.
This attack is also only able to be propagated on client instances
that talk to more than one AS at runtime, which can be limited by the
client software.
Paragraph (version A):
The need for accommodating such known delays in the system needs to
be balanced with the risk of allowing an old key to still be used.
Narrowly restricting the exposure opportunities for exploit at the AS
in terms of time, place, and method makes exploit significantly more
difficult, especially if the exception happens only once.  For
example, the AS can reject requests from the previously-bound key (or
any previous one before it) to cause rotation to a new key, or at
least ensure that the rotation happens to the same known key.
Paragraph (version B):
The need for accommodating such known delays in the system needs to
be balanced with the risk of allowing an old key to still be used.
Narrowly restricting the exposure opportunities for exploit at the AS
in terms of time, place, and method makes exploit significantly more
difficult, especially if the exception happens only once.  For
example, the AS can reject requests from the previously-bound key (or
any previous one before it) to cause rotation to a new key, or at
least ensure that the rotation happens in an idempotent way to the
same new key.
Paragraph (version A):
Some types of client deployment are unable to receive an interaction
finish message.  Without an interaction finish method to notify it,
the client instance will need to poll the grant continuation API
while waiting for the resource owner to approve or deny the request.
An attacker could take advantage of this situation by capturing the
interaction start parameters and phishing a legitimate user into
authorizing the attacker's waiting client instance, which would in
turn have no way of associating the completed interaction with the
start of the request.
Paragraph (version B):
Some types of client deployment are unable to receive an interaction
finish message.  Without an interaction finish method to notify it,
the client instance will need to poll the grant continuation API
while waiting for the resource owner to approve or deny the request.
An attacker could take advantage of this situation by capturing the
interaction start parameters and phishing a legitimate user into
authorizing the attacker's waiting client instance, which would in
turn have no way of associating the completed interaction from the
targeted user with the start of the request from the attacker.
Paragraph (version A):
When using an interaction finish method such as "redirect" or "push",
the client instance receives an unsolicited HTTP request from an
unknown party.  The client instance needs to be able to successfully
associate this incoming request with a specific pending grant request
being managed by the client instance.  If the client instance is not
careful and precise about this, an attacker could associate their own
session at the client instance with a stolen interaction response.
The means of preventing this varies by the type of client software
and interaction methods in use.  Some common patterns are enumerated
here.
Paragraph (version B):
When using an interaction finish method such as "redirect" or "push",
the client instance receives an unsolicited inbound request from an
unknown party (in most cases over HTTP).  The client instance needs
to be able to successfully associate this incoming request with a
specific pending grant request being managed by the client instance.
If the client instance is not careful and precise about this, an
attacker could associate their own session at the client instance
with a stolen interaction response.  The means of preventing this
varies by the type of client software and interaction methods in use.
Some common patterns are enumerated here.
Paragraph (version A):
instance can then detect that it is not the party that started the
request that is present, since the request at the honest client
instance was started by the attacker, which can prevent the attack.
This is related to security-impersonation, because again the attack
can be prevented by the AS informing the user as much as possible
about the client instance that is to be authorized.
Paragraph (version B):
instance can then detect that the end user is not the party that
started the request, since the request at the honest client instance
was started by the attacker.  This detection can prevent the attack.
This is related to the discussion in security-impersonation, because
again the attack can be prevented by the AS informing the user as
much as possible about the client instance that is to be authorized.
Paragraph (version A):
If the client instance does not have the ability to use an
interaction finish method, it can use polling to continue the
request.  The tradeoffs of this approach are discussed in security-
polling, and if possible, an explicit interaction finish method
should be used instead.
Paragraph (version A):
The calculation of the interaction hash value provides defence in
depth, allowing a client instance to protect itself from spurious
injection of interaction references when using a callback finish
method.  The AS is protected during this attack through the
continuation access token being bound to the expected interaction
reference, but without hash calculation, the attacker could cause the
client to make an HTTP request on command.  With both of these in
place, an attacker attempting to substitute the interaction reference
is stopped in several places.
Paragraph (version B):
The calculation of the interaction hash value provides defence in
depth, allowing a client instance to protect itself from spurious
injection of interaction references when using an interaction finish
method.  The AS is protected during this attack through the
continuation access token being bound to the expected interaction
reference, but without hash calculation, the attacker could cause the
client to make an HTTP request on command.  With both of these in
place, an attacker attempting to substitute the interaction reference
is stopped in several places.
Paragraph (version A):
When starting an interactive grant request, a client application has
a number of protocol elements that it needs to manage, including
nonces, references, keys, access tokens, and other elements.  During
the interaction process, the client instance usually hands control of
the user experience over to another component, beit the system
browser, another application, or some action the resource owner is
instructed to take on another device.  In order for the client
instance to make its continuation call, it will need to recall all of
these protocol elements.  Usually this means the client instance will
need to store these protocol elements in some retrievable fashion.
Paragraph (version B):
When starting an interactive grant request, a client application has
a number of protocol elements that it needs to manage, including
nonces, references, keys, access tokens, and other elements.  During
the interaction process, the client instance usually hands control of
the user experience over to another component, beit the system
browser, another application, or some action the resource owner is
instructed to take on another device.  In order for the client
instance to make its continuation call, it will need to recall all of
these protocol elements at a future time.  Usually this means the
client instance will need to store these protocol elements in some
retrievable fashion.
Paragraph (version A):
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 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, and that value should be
used to index into a secure session or storage mechanism.
Paragraph (version A):
To combat this, both continue-request and token-management are
designed to be idempotent, where subsequent calls to the same
function with the same credentials are meant to produce the same
results.  For example, multiple calls to rotate the same access token
need to result in the same rotated token value.
Paragraph (version B):
To combat this, both continue-request and token-management can be
designed to be idempotent, where subsequent calls to the same
function with the same credentials are meant to produce the same
results.  For example, multiple calls to rotate the same access token
need to result in the same rotated token value, within a reasonable
time window.
Paragraph (version A):
In practice, an AS can hold on to an old token value for such limited
purposes.  For example, to support rotating access tokens over
unreliable networks, the AS receives the initial request to rotate an
access token and creates a new token value and returns it.  The AS
also marks the old token value as having been used to create the
newly-rotated token value.  If the AS sees the old token value within
a small enough time window, such as a few seconds since the first
rotation attempt, the AS can return the same rotated access token.
Furthermore, once the system has seen the newly-rotated token in use,
the original token can be discarded because the client instance has
proved that it did receive the token.  The result of this is a system
that is eventually self-consistent without placing an undue
complexity burden on the client instance.
Paragraph (version B):
In practice, an AS can hold on to an old token value for such limited
purposes.  For example, to support rotating access tokens over
unreliable networks, the AS receives the initial request to rotate an
access token and creates a new token value and returns it.  The AS
also marks the old token value as having been used to create the
newly-rotated token value.  If the AS sees the old token value within
a small enough time window, such as a few seconds since the first
rotation attempt, the AS can return the same rotated access token
value.  Furthermore, once the system has seen the newly-rotated token
in use, the original token can be discarded because the client
instance has proved that it did receive the token.  The result of
this is a system that is eventually self-consistent without placing
an undue complexity burden on the client instance to manage
problematic networks.
Paragraph (version A):
endpoints.
Paragraph (version B):
endpoints.  This can be particularly problematic if such a URI is
used to call non-HTTP endpoints, such as remote code execution
services local to the AS.
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 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):
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.  Even if the
AS does not fetch these URIs, their use in GNAP's normal operation
could cause an attack against the end user's browser as it fetches
these same attack URIs.  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 A):
Keys presented by value are allowed to be in only a single format, as
discussed in key-format.  Presenting the same key in multiple formats
is not allowed and is considered an error in the request.  If
multiple keys formats were allowed, receivers of these key
definitions need to be able to make sure that it's the same key
represented in each field and not simply use one of the key formats
without checking for equivalence.  If equivalence were not carefully
checked, it is possible for an attacker to insert their own key into
one of the formats without needing to have control over the other
formats.  This could potentially lead to a situation where one key is
used by part of the system (such as identifying the client instance)
and a different key in a different format in the same message is used
for other things, like calculating signature validity.
Paragraph (version A):
To combat this, all keys presented by value have to be in exactly one
supported format known by the receiver.  Normally, a client instance
is going to be configured with its keys in a single format, and it
will simply present that format as-is to the AS in its request.  A
client instance capable of multiple formats can use discovery to
determine which formats are supported, if desired.  An AS should be
generous in supporting many different key formats to allow different
types of client software and client instance deployments.
Paragraph (version B):
All keys presented by value are allowed to be in only a single
format.  While it would seem beneficial to allow keys to be sent in
multiple formats, in case the receiver doesn't understand one or more
of the formats used, there would be security issues with such a
feature.  If multiple keys formats were allowed, receivers of these
key definitions would need to be able to make sure that it's the same
key represented in each field and not simply use one of the key
formats without checking for equivalence.  If equivalence were not
carefully checked, it is possible for an attacker to insert their own
key into one of the formats without needing to have control over the
other formats.  This could potentially lead to a situation where one
key is used by part of the system (such as identifying the client
instance) and a different key in a different format in the same
message is used for other things (such as calculating signature
validity).  However, in such cases, it is impossible for the receiver
to ensure that all formats contain the same key information since it
is assumed that the receiver cannot understand all of the formats.
Paragraph (version B):
To combat this, all keys presented by value have to be in exactly one
supported format known by the receiver as discussed in key-format.
In most cases, a client instance is going to be configured with its
keys in a single format, and it will simply present that format as-is
to the AS in its request.  A client instance capable of multiple
formats can use discovery to determine which formats are supported,
if desired.  An AS should be generous in supporting many different
key formats to allow different types of client software and client
instance deployments.  An AS implementation should try to support
multiple formats to allow a variety of client software to connect.
Paragraph (version A):
GNAP assumes the TLS protection used throughout the spec is intact.
Without the protection of TLS, there are many points throughout the
use of GNAP that would lead to possible surveillance.
Paragraph (version B):
GNAP assumes the TLS protection used throughout the spec is intact.
Without the protection of TLS, there are many points throughout the
use of GNAP that would lead to possible surveillance.  Even with the
proper use of TLS, surveillance could occur by several parties
outside of the TLS-protected channels, as discussed in the sections
below.
Paragraph (version A):
The purpose of GNAP is to authorize clients to be able to access
information on behalf of a user.  So while it is expected that the
client may be aware of the user's identity as well as data being
fetched for that user, in some cases the extent of the client may be
beyond what the user is aware of.  For example, a client may be
implemented as multiple distinct pieces of software, such as a
logging service or a mobile app that reports usage data to an
external backend service.
Paragraph (version B):
The purpose of GNAP is to authorize clients to be able to access
information on behalf of a user.  So while it is expected that the
client may be aware of the user's identity as well as data being
fetched for that user, in some cases the extent of the client may be
beyond what the user is aware of.  For example, a client may be
implemented as multiple distinct pieces of software, such as a
logging service or a mobile app that reports usage data to an
external backend service.  Each of these pieces could gain
information about the user without the user being aware of this
action.
Paragraph (version A):
The client is expected to store its client instance key indefinitely,
in order to authenticate to the authorization server for the normal
functioning of the GNAP flows.  Additionally, the client will be
temporarily storing artifacts issued by the authorization server
during a flow, and these artifacts SHOULD be discarded by the client
when the transaction is complete.
Paragraph (version A):
The resource server is not required to store any state for its normal
operation.  Depending on the implementation of access tokens, the
resource server may need to cache public keys from the authorization
server in order to validate access tokens.
Paragraph (version B):
The client is expected to store its client instance key indefinitely,
in order to authenticate to the authorization server for the normal
functioning of the GNAP flows.  Additionally, the client will be
temporarily storing artifacts issued by the authorization server
during a flow, and these artifacts ought to be discarded by the
client when the transaction is complete.
Paragraph (version B):
The resource server is not required to store any state for its normal
operation, as far as its part in implementing GNAP.  Depending on the
implementation of access tokens, the resource server may need to
cache public keys from the authorization server in order to validate
access tokens.
Paragraph (version A):
The most common example of this in practice is tracking for
advertising purposes, such that client A shares their list of user
IDs with an ad platform that is then able to retarget ads to
applications created by other parties.  In contrast, a positive
example of correlation is a corporate acquisition where two
previously unrelated clients now do need to be able to identify the
same user between the two clients.
Paragraph (version B):
The most common example of this in practice is tracking for
advertising purposes, such that a client shares their list of user
IDs with an ad platform that is then able to retarget ads to
applications created by other parties.  In contrast, a positive
example of correlation is a corporate acquisition where two
previously unrelated clients now do need to be able to identify the
same user between the two clients, such as when software systems are
intentionally connected by the end user.
Paragraph (version B):
Another means of correlation comes from the use of rs-request-
without-token.  A client instance knowing nothing other than an RS's
URL could make an unauthenticated call to the RS and learn which AS
protects the resources there.  If the client instance knows something
about the AS, such as it being a single-user AS or belonging to a
specific organization, the client instance could, through
association, learn things about the resource without ever gaining
access to the resource itself.