Draft: draft-ietf-gnap-core-protocol

Commentary: fix typos 
 Built To edit notification comments on pull requests , go to your . 
 Removing the editorial label after the last change ( which is normative ) 
 This discovery method is great for usability but worrying from a security POV . The RS is telling the Client to create a request to an arbitrary AS using an arbitrary access specification and the Client 's credentials . The  does n't have any way to understand , validate or filter anything in the RS 's response , so it can not protect itself . By the way , should n't we use a semicolon before the parameter ? A possible workaround is to add something analogous to a parameter to the AS access request containing the RS address , require the  to include it , and require that the AS validate that the request is indeed to that RS . 
 In this scenario the client is explicitly looking to the RS to provide a pointer to which AS to talk to . In most cases this is pre - configured ( the client knows which AS protects which RS ) . In some cases this will be communicated at runtime , using this mechanism . There are both security and privacy ramifications for this choice , which we 've covered at least some of in the current text . I 'm sure this can be expanded . 
 GNAP is a delegation protocol that enables separation of control from processing with obvious advantages to all three parties ( subject , controller , processor ) . The RS is typically a processor . The choice of AS as delegated controller SHOUlD lie with the subject in order to better represent their interest . This perspective is , of course , not absolute but it the should makes it the preferred path . 
 I do n't see anything explicit about this call . The client just makes a normal - but - unauthenticated call to the RS , with no special indication that it 's doing discovery . In fact a malicious RS can redirect the client anyway , even if the client is in fact authenticated . And I do n't see anything in the text about the threat vector of a malicious RS . Please also respond to my syntactic comment above . 
 I 've got a few comments on wording . Mostly though : I 'm not sure about changing the field to , since it 's not just ANY opaque value but specifically an opaque value for use in the access section of the request . As such , I think is too generic in this use . If we change the parameter name back I think this is OK .
Paragraph (version A):
If the client instance calls an RS without an access token, or with
an invalid access token, the RS SHOULD respond to the client instance
with a WWW-Authenticate header field indicating that GNAP needs to be
used to access the resource.  The address of the GNAP endpoint MUST
be sent in the "as_uri" parameter.  The RS MAY additionally return a
resource reference that the client instance SHOULD use in its access
token request.  This resource reference MUST be sufficient for at
least the action the client instance was attempting to take at the RS
and MAY be more powerful.  The means for the RS to determine the
resource reference are out of scope of this specification, but some
dynamic methods are discussed in I-D.ietf-gnap-resource-servers.  The
content of the resource reference is opaque to the client instance.
Paragraph (version A):
The client instance then makes a request to the "as_uri" as described
in request, with the value of "access" as one of the members of the
"access" array in the "access_token" portion of the request.  The
client instance MAY request additional resources and other
information.  The client instance MAY request multiple access tokens.
Paragraph (version A):
In this non-normative example, the client instance is requesting a
single access token using the resource reference "FWWIKYBQ6U56NL1"
received from the RS in addition to the "dolphin-metadata" resource
reference that the client instance has been configured with out of
band.
Paragraph (version B):
If the client instance calls an RS without an access token, or with
an invalid access token, the RS SHOULD be explicit about the fact
that GNAP needs to be used to access the resource, by responding with
the WWW-Authenticate header field and a GNAP challenge.
Paragraph (version B):
In some situations, the client instance might want to know with which
specific AS it needs to negotiate for access to that RS.  The RS MAY
additionally return the address of the GNAP endpoint in the "as_uri"
parameter, a "referrer" parameter to indicate which RS initiated the
discovery process, and an opaque "access" reference.  The client
instance SHOULD then use both the "referrer" and "access" parameters
in its access token request.  The "referrer" parameter MUST be the
URI of the RS, and the client instance MUST check its value to
protect itself.  The opaque "access" reference MUST be sufficient for
at least the action the client instance was attempting to take at the
RS and MAY be more powerful.
Paragraph (version B):
The means for the RS to determine the value for the "access"
reference are out of scope of this specification, but some dynamic
methods are discussed in I-D.ietf-gnap-resource-servers.
Paragraph (version B):
The client instance then makes a request to the "as_uri" as described
in request, with the value of "referrer" passed as an HTTP Referer
header field and the "access" reference passed unchanged into the
"access" array in the "access_token" portion of the request.  The
client instance MAY request additional resources and other
information.
Paragraph (version B):
In this non-normative example, the client instance is requesting a
single access token using the opaque access reference
"FWWIKYBQ6U56NL1" received from the RS in addition to the "dolphin-
metadata" that the client instance has been configured with out of
band.
Paragraph (version B):
The client instance includes the Referer header field as a way for
the AS to know that the process is initiated through a discovery
process at the RS.
Paragraph (version B):
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):
An attacker may aim to gain access to confidential or sensitive
resources.  The measures for hardening and monitoring resource server
systems (beyond protection with access tokens) is out of the scope of
this document, but the use of GNAP to protect a system does not
absolve the resource server of following best practices.  GNAP
generally considers a breach can occur, and therefore advises to
prefer key-bound tokens whenever possible, which at least limits the
impact of access token leakage by a compromised or malicious RS.