Draft: draft-ietf-gnap-core-protocol

Commentary: Section 1.2 only defines the role of an , so I thought this should be written consistently that way . 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Built Explore the source changes : Inspect the deploy log : Browse the preview : 
 Yes that 's good 
 Upon review ( thanks  ) , it should be unhyphenated as a noun . We sure need to be consistent everywhere . See 
 I have replaced the unambiguous uses of " end - user " as a noun with " end user " . I am not sure about " end - user roles " in line 232 and " Exposure of end - user credentials " in line 4878 . I left these lines as before ( hyphenated ) . Someone else should look at these lines again .
Paragraph (version A):
This protocol allows a piece of software, the client instance, to
request delegated authorization to resource servers and to request
direct 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):
This protocol allows a piece of software, the client instance, to
request delegated authorization to resource servers and to request
direct 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 A):
Multiple roles can be fulfilled by the same party, and a given party
can switch roles in different instances of the protocol.  For
example, the RO and end-user in many instances are the same person,
where a user is authorizing the client instance to act on their own
behalf at the RS.  In this case, one party fulfills both of the RO
and end-user roles, but the roles themselves are still defined
separately from each other to allow for other use cases where they
are fulfilled by different parties.
Paragraph (version B):
Multiple roles can be fulfilled by the same party, and a given party
can switch roles in different instances of the protocol.  For
example, the RO and end user in many instances are the same person,
where a user is authorizing the client instance to act on their own
behalf at the RS.  In this case, one party fulfills both of the RO
and end-user roles, but the roles themselves are still defined
separately from each other to allow for other use cases where they
are fulfilled by different parties.
Paragraph (version A):
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 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.
Paragraph (version A):
end-user/RO: this relationship exists only when the end-user and
the RO are different, in which case the end-user needs some out of
band mechanism of getting the RO consent (see authorization).
GNAP generally assumes that humans can be authenticated thanks to
identity protocols (for instance, through an id_token assertion in
request-subject).
Paragraph (version A):
end-user/client: the client acts as a user agent.  Depending on
the technology used (browser, SPA, mobile application, IoT device,
etc.), some interactions may or may not be possible (as described
in request-interact-start).  Client developers promise to
implement requirements and generally some recommendations or best
practices, so that the end-users may confidently use their
software.  However, end-users might also be facing some attacker's
client software, without even realizing it.
Paragraph (version A):
end-user / AS: when the client supports it (see response-
interact), the end-user gets to interact with front-channel URLs
provided by the AS.  See security-front-channel for some
considerations in trusting these interactions.
Paragraph (version B):
end user/RO: this relationship exists only when the end user and
the RO are different, in which case the end user needs some out of
band mechanism of getting the RO consent (see authorization).
GNAP generally assumes that humans can be authenticated thanks to
identity protocols (for instance, through an id_token assertion in
request-subject).
Paragraph (version B):
end user/client: the client acts as a user agent.  Depending on
the technology used (browser, SPA, mobile application, IoT device,
etc.), some interactions may or may not be possible (as described
in request-interact-start).  Client developers promise to
implement requirements and generally some recommendations or best
practices, so that the end users may confidently use their
software.  However, end users might also be facing some attacker's
client software, without even realizing it.
Paragraph (version B):
end user/AS: when the client supports it (see response-interact),
the end user gets to interact with front-channel URLs provided by
the AS.  See security-front-channel for some considerations in
trusting these interactions.
Paragraph (version A):
In this example flow, the client instance is a web application that
wants access to resources on behalf of the current user, who acts as
both the end-user and the resource owner (RO).  Since the client
instance is capable of directing the user to an arbitrary URL and
receiving responses from the user's browser, interaction here is
handled through front-channel redirects using the user's browser.
The redirection URL used for interaction is a service hosted by the
AS in this example.  The client instance uses a persistent session
with the user to ensure the same user that is starting the
interaction is the user that returns from the interaction.
Paragraph (version B):
In this example flow, the client instance is a web application that
wants access to resources on behalf of the current user, who acts as
both the end user and the resource owner (RO).  Since the client
instance is capable of directing the user to an arbitrary URL and
receiving responses from the user's browser, interaction here is
handled through front-channel redirects using the user's browser.
The redirection URL used for interaction is a service hosted by the
AS in this example.  The client instance uses a persistent session
with the user to ensure the same user that is starting the
interaction is the user that returns from the interaction.
Paragraph (version A):
The client instance establishes a verifiable session to the user,
in the role of the end-user.
Paragraph (version B):
The client instance establishes a verifiable session to the user,
in the role of the end user.
Paragraph (version A):
also needs to be prepared for the end-user never being returned to
the client instance and handle timeouts appropriately.
Paragraph (version B):
also needs to be prepared for the end user never being returned to
the client instance and handle timeouts appropriately.
Paragraph (version A):
In this example flow, the client instance is a device that is capable
of presenting a short, human-readable code to the user and directing
the user to enter that code at a known URL.  The URL the user enters
the code at is an interactive service hosted by the AS in this
example.  The client instance is not capable of presenting an
arbitrary URL to the user, nor is it capable of accepting incoming
HTTP requests from the user's browser.  The client instance polls the
AS while it is waiting for the RO to authorize the request.  The
user's interaction is assumed to occur on a secondary device.  In
this example it is assumed that the user is both the end-user and RO,
though the user is not assumed to be interacting with the client
instance through the same web browser used for interaction at the AS.
Paragraph (version B):
In this example flow, the client instance is a device that is capable
of presenting a short, human-readable code to the user and directing
the user to enter that code at a known URL.  The URL the user enters
the code at is an interactive service hosted by the AS in this
example.  The client instance is not capable of presenting an
arbitrary URL to the user, nor is it capable of accepting incoming
HTTP requests from the user's browser.  The client instance polls the
AS while it is waiting for the RO to authorize the request.  The
user's interaction is assumed to occur on a secondary device.  In
this example it is assumed that the user is both the end user and RO,
though the user is not assumed to be interacting with the client
instance through the same web browser used for interaction at the AS.
Paragraph (version A):
The end-user authenticates at the AS, taking on the role of the
RO.
Paragraph (version B):
The end user authenticates at the AS, taking on the role of the
RO.
Paragraph (version A):
In this example flow, the end-user and RO roles are fulfilled by
different parties, and the RO does not interact with the client
instance.  The AS reaches out asynchronously to the RO during the
request process to gather the RO's authorization for the client
instance's request.  The client instance polls the AS while it is
waiting for the RO to authorize the request.
Paragraph (version B):
In this example flow, the end user and RO roles are fulfilled by
different parties, and the RO does not interact with the client
instance.  The AS reaches out asynchronously to the RO during the
request process to gather the RO's authorization for the client
instance's request.  The client instance polls the AS while it is
waiting for the RO to authorize the request.
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 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
error.
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.
Paragraph (version B):
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
error.
Paragraph (version A):
The AS can identify the current end-user to the client instance with
a reference which can be used by the client instance to refer to the
end-user across multiple requests.  If the client instance has a
reference for the end-user at this AS, the client instance MAY pass
that reference as a string.  The format of this string is opaque to
the client instance.
Paragraph (version B):
The AS can identify the current end user to the client instance with
a reference which can be used by the client instance to refer to the
end user across multiple requests.  If the client instance has a
reference for the end user at this AS, the client instance MAY pass
that reference as a string.  The format of this string is opaque to
the client instance.
Paragraph (version A):
Often, the AS will require authorization in order to approve a
requested delegation to the client instance for both access to
resources and direct subject information.  Many times the end-user
using the client instance is the same person as the RO, and the
client instance can directly drive interaction with the end user by
facilitating the process through means such as redirection to a URL
or launching an application.  Other times, the client instance can
provide information to start the RO's interaction on a secondary
device, or the client instance will wait for the RO to approve the
request asynchronously.  The client instance could also be signaled
that interaction has concluded through a callback mechanism.
Paragraph (version B):
Often, the AS will require authorization in order to approve a
requested delegation to the client instance for both access to
resources and direct subject information.  Many times the end user
using the client instance is the same person as the RO, and the
client instance can directly drive interaction with the end user by
facilitating the process through means such as redirection to a URL
or launching an application.  Other times, the client instance can
provide information to start the RO's interaction on a secondary
device, or the client instance will wait for the RO to approve the
request asynchronously.  The client instance could also be signaled
that interaction has concluded through a callback mechanism.
Paragraph (version A):
In this non-normative example, the client instance is indicating that
it can request-interact-redirect the end-user to an arbitrary URL and
can receive a request-interact-callback-redirect through a browser
request.
Paragraph (version A):
In this non-normative example, the client instance is indicating that
it can display a request-interact-usercode and direct the end-user to
an request-interact-redirect on a secondary device, but it cannot
accept a redirect or push callback.
Paragraph (version B):
In this non-normative example, the client instance is indicating that
it can request-interact-redirect the end user to an arbitrary URL and
can receive a request-interact-callback-redirect through a browser
request.
Paragraph (version B):
In this non-normative example, the client instance is indicating that
it can display a request-interact-usercode and direct the end user to
an request-interact-redirect on a secondary device, but it cannot
accept a redirect or push callback.
Paragraph (version A):
If the client instance is capable of directing the end-user to a URL
defined by the AS at runtime, the client instance indicates this by
including "redirect" in the array under the "start" key.  The means
by which the client instance will activate this URL is out of scope
of this specification, but common methods include an HTTP redirect,
launching a browser on the end-user's device, providing a scannable
image encoding, and printing out a URL to an interactive console.
While this URL is generally hosted at the AS, the client instance can
make no assumptions about its contents, composition, or relationship
to the AS grant URL.
Paragraph (version B):
If the client instance is capable of directing the end user to a URL
defined by the AS at runtime, the client instance indicates this by
including "redirect" in the array under the "start" key.  The means
by which the client instance will activate this URL is out of scope
of this specification, but common methods include an HTTP redirect,
launching a browser on the end user's device, providing a scannable
image encoding, and printing out a URL to an interactive console.
While this URL is generally hosted at the AS, the client instance can
make no assumptions about its contents, composition, or relationship
to the AS grant URL.
Paragraph (version A):
If the client instance can open a URL associated with an application
on the end-user's device, the client instance indicates this by
including "app" in the array under the "start" key.  The means by
which the client instance determines the application to open with
this URL are out of scope of this specification.
Paragraph (version B):
If the client instance can open a URL associated with an application
on the end user's device, the client instance indicates this by
including "app" in the array under the "start" key.  The means by
which the client instance determines the application to open with
this URL are out of scope of this specification.
Paragraph (version A):
Since the incoming request to the callback URL is from the RO's
browser, this method is usually used when the RO and end-user are the
same entity.  As such, the client instance MUST ensure the end-user
is present on the request to prevent substitution attacks.
Paragraph (version B):
Since the incoming request to the callback URL is from the RO's
browser, this method is usually used when the RO and end user are the
same entity.  As such, the client instance MUST ensure the end user
is present on the request to prevent substitution attacks.
Paragraph (version A):
Since the incoming request to the callback URL is from the AS and not
from the RO's browser, the client instance MUST NOT require the end-
user to be present on the incoming HTTP request.
Paragraph (version B):
Since the incoming request to the callback URL is from the AS and not
from the RO's browser, the client instance MUST NOT require the end
user to be present on the incoming HTTP request.
Paragraph (version A):
If the client instance knows the end-user's locale and language
preferences, the client instance can send this information to the AS
using the "ui_locales" field with an array of locale strings as
defined by RFC5646.
Paragraph (version B):
If the client instance knows the end user's locale and language
preferences, the client instance can send this information to the AS
using the "ui_locales" field with an array of locale strings as
defined by RFC5646.
Paragraph (version A):
If the client instance indicates that it can request-interact-
redirect and the AS supports this mode for the client instance's
request, the AS responds with the "redirect" field, which is a string
containing the URL to direct the end-user to.  This URL MUST be
unique for the request and MUST NOT contain any security-sensitive
information such as user identifiers or access tokens.
Paragraph (version B):
If the client instance indicates that it can request-interact-
redirect and the AS supports this mode for the client instance's
request, the AS responds with the "redirect" field, which is a string
containing the URL to direct the end user to.  This URL MUST be
unique for the request and MUST NOT contain any security-sensitive
information such as user identifiers or access tokens.
Paragraph (version A):
The client instance sends the end-user to the URL to interact with
the AS.  The client instance MUST NOT alter the URL in any way.  The
means for the client instance to send the end-user to this URL is out
of scope of this specification, but common methods include an HTTP
redirect, launching the system browser, displaying a scannable code,
or printing out the URL in an interactive console.  See details of
the interaction in interaction-redirect.
Paragraph (version B):
The client instance sends the end user to the URL to interact with
the AS.  The client instance MUST NOT alter the URL in any way.  The
means for the client instance to send the end user to this URL is out
of scope of this specification, but common methods include an HTTP
redirect, launching the system browser, displaying a scannable code,
or printing out the URL in an interactive console.  See details of
the interaction in interaction-redirect.
Paragraph (version A):
The client instance MUST communicate the "code" to the end-user in
some fashion, such as displaying it on a screen or reading it out
audibly.
Paragraph (version B):
The client instance MUST communicate the "code" to the end user in
some fashion, such as displaying it on a screen or reading it out
audibly.
Paragraph (version A):
The client instance SHOULD also communicate the URL if possible to
facilitate user interaction, but since the URL should be stable, the
client instance should be able to safely decide to not display this
value.  As this interaction mode is designed to facilitate
interaction via a secondary device, it is not expected that the
client instance redirect the end-user to the URL given here at
runtime.  Consequently, the URL needs to be stable enough that a
client instance could be statically configured with it, perhaps
referring the end-user to the URL via documentation instead of
through an interactive means.  If the client instance is capable of
communicating an arbitrary URL to the end-user, such as through a
scannable code, the client instance can use the request-interact-
redirect mode for this purpose instead of or in addition to the user
code mode.
Paragraph (version B):
The client instance SHOULD also communicate the URL if possible to
facilitate user interaction, but since the URL should be stable, the
client instance should be able to safely decide to not display this
value.  As this interaction mode is designed to facilitate
interaction via a secondary device, it is not expected that the
client instance redirect the end user to the URL given here at
runtime.  Consequently, the URL needs to be stable enough that a
client instance could be statically configured with it, perhaps
referring the end user to the URL via documentation instead of
through an interactive means.  If the client instance is capable of
communicating an arbitrary URL to the end user, such as through a
scannable code, the client instance can use the request-interact-
redirect mode for this purpose instead of or in addition to the user
code mode.
Paragraph (version A):
If information about the RO is requested and the AS grants the client
instance access to that data, the AS returns the approved information
in the "subject" response field.  The AS MUST return the "subject"
field only in cases where the AS is sure that the RO and the end-user
are the same party.  This can be accomplished through some forms of
authorization.
Paragraph (version B):
If information about the RO is requested and the AS grants the client
instance access to that data, the AS returns the approved information
in the "subject" response field.  The AS MUST return the "subject"
field only in cases where the AS is sure that the RO and the end user
are the same party.  This can be accomplished through some forms of
authorization.
Paragraph (version A):
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.  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):
When the end user is directed to enter a short code through the
response-interact-usercode mode, the client instance communicates the
user code to the end-user and directs the end user to enter that code
at an associated URI.  This mode is used when the client instance is
not able to facilitate launching an arbitrary URI.  The associated
URI could be statically configured with the client instance or
communicated in the response from the AS, but the client instance
communicates that URL to the end user.  As a consequence, these URIs
SHOULD be short.
Paragraph (version B):
When the end user is directed to enter a short code through the
response-interact-usercode mode, the client instance communicates the
user code to the end user and directs the end user to enter that code
at an associated URI.  This mode is used when the client instance is
not able to facilitate launching an arbitrary URI.  The associated
URI could be statically configured with the client instance or
communicated in the response from the AS, but the client instance
communicates that URL to the end user.  As a consequence, these URIs
SHOULD be short.
Paragraph (version A):
end-user to copy keys between client instances and to willingly use
the same key in multiple instances.
Paragraph (version A):
The AS performs critical functions in GNAP, including authenticating
client software, managing interactions with end-users to gather
consent and provide notice, and issuing access tokens for client
instances to present to resource servers.  As such, protecting the AS
is central to any GNAP deployment.
Paragraph (version B):
end user to copy keys between client instances and to willingly use
the same key in multiple instances.
Paragraph (version B):
The AS performs critical functions in GNAP, including authenticating
client software, managing interactions with end users to gather
consent and provide notice, and issuing access tokens for client
instances to present to resource servers.  As such, protecting the AS
is central to any GNAP deployment.
Paragraph (version A):
As a delegation protocol, one of the main goals of GNAP is to prevent
the client software from being exposed to any credentials or
information about the end-user or resource owner as a requirement of
the delegation process.  By using the variety of interaction
mechanisms, the resource owner can interact with the AS without ever
authenticating to the client software, and without the client
software having to impersonate the resource owner through replay of
their credentials.
Paragraph (version B):
As a delegation protocol, one of the main goals of GNAP is to prevent
the client software from being exposed to any credentials or
information about the end user or resource owner as a requirement of
the delegation process.  By using the variety of interaction
mechanisms, the resource owner can interact with the AS without ever
authenticating to the client software, and without the client
software having to impersonate the resource owner through replay of
their credentials.
Paragraph (version A):
Consequently, no interaction methods defined in the GNAP core require
the end-user to enter their credentials, but it is technologically
possible for an extension to be defined to carry such values.  Such
an extension would be dangerous as it would allow rogue client
software to directly collect, store, and replay the end-user's
credentials outside of any legitimate use within a GNAP request.
Paragraph (version B):
Consequently, no interaction methods defined in the GNAP core require
the end user to enter their credentials, but it is technologically
possible for an extension to be defined to carry such values.  Such
an extension would be dangerous as it would allow rogue client
software to directly collect, store, and replay the end user's
credentials outside of any legitimate use within a GNAP request.
Paragraph (version A):
It also is sensible to pre-register client instances when the
software is acting autonomously, without the need for a runtime
approval by a resource owner or any interaction with an end-user.  In
these cases, an AS needs to rest on the trust decisions that have
been determined prior to runtime in determining what rights and
tokens to grant to a given client instance.
Paragraph (version B):
It also is sensible to pre-register client instances when the
software is acting autonomously, without the need for a runtime
approval by a resource owner or any interaction with an end user.  In
these cases, an AS needs to rest on the trust decisions that have
been determined prior to runtime in determining what rights and
tokens to grant to a given client instance.
Paragraph (version A):
An AS can treat these classes of client software differently from
each other, perhaps by allowing access to certain high-value APIs
only to pre-registered known clients, or by requiring an active end-
user delegation of authority to any client software not pre-
registered.
Paragraph (version B):
An AS can treat these classes of client software differently from
each other, perhaps by allowing access to certain high-value APIs
only to pre-registered known clients, or by requiring an active end
user delegation of authority to any client software not pre-
registered.
Paragraph (version A):
If the security protocol elements are stored on the end-user's
device, such as in browser storage or in local application data
stores, capture and exfiltration of this information could allow an
attacker to continue a pending transaction instead of the client
instance.  Client software can make use of secure storage mechanisms,
including hardware-based key and data storage, to prevent such
exfiltration.
Paragraph (version B):
If the security protocol elements are stored on the end user's
device, such as in browser storage or in local application data
stores, capture and exfiltration of this information could allow an
attacker to continue a pending transaction instead of the client
instance.  Client software can make use of secure storage mechanisms,
including hardware-based key and data storage, to prevent such
exfiltration.
Paragraph (version A):
Some interaction methods in GNAP make use of URLs accessed through
the end-user's browser, known collectively as front-channel
communication.  These URLs are most notably present in the "redirect"
interaction "start" method and the "redirect" interaction "finish"
mode.  Since these URLs are intended to be given to the end-user, the
end user and their browser will be subjected to anything hosted at
that URL including viruses, malware, and phishing scams.  This kind
of risk is inherent to all redirection-based protocols, including
GNAP when used in this way.
Paragraph (version B):
Some interaction methods in GNAP make use of URLs accessed through
the end user's browser, known collectively as front-channel
communication.  These URLs are most notably present in the "redirect"
interaction "start" method and the "redirect" interaction "finish"
mode.  Since these URLs are intended to be given to the end user, the
end user and their browser will be subjected to anything hosted at
that URL including viruses, malware, and phishing scams.  This kind
of risk is inherent to all redirection-based protocols, including
GNAP when used in this way.
Paragraph (version A):
When talking to a new or unknown AS, a client instance might want to
check the URL from the interaction "start" against a blocklist and
warn the end-user before redirecting them.  Many client instances
will provide an interstitial message prior to redirection in order to
prepare the user for control of the user experience being handed to
the domain of the AS, and such a method could be used to warn the
user of potential threats.  For instance, a rogue AS impersonating a
well-known service provider.  Client software can also prevent this
by managing an allowlist of known and trusted AS's.
Paragraph (version B):
When talking to a new or unknown AS, a client instance might want to
check the URL from the interaction "start" against a blocklist and
warn the end user before redirecting them.  Many client instances
will provide an interstitial message prior to redirection in order to
prepare the user for control of the user experience being handed to
the domain of the AS, and such a method could be used to warn the
user of potential threats.  For instance, a rogue AS impersonating a
well-known service provider.  Client software can also prevent this
by managing an allowlist of known and trusted AS's.
Paragraph (version A):
URL, the AS can provide an interstitial warning to the end-user
before processing the redirect.
Paragraph (version B):
URL, the AS can provide an interstitial warning to the end user
before processing the redirect.