[GNAP] Quick review of draft-ietf-gnap-core-protocol-00

[Denis <[e-mail]>]

Hi,

I haven't read all the document in details, but I have browsed through 
it: this took me about 3 hours.
As it is, I don't consider that the current text (more than 100 pages !) 
is a "good starting point".

The less that I can say is that the document is far from being crystal 
clear, is too complex and includes so many options
(without indicating which parameters are required and which ones are 
optional) that it will be impossible to claim that
an implementation complies with it.

In addition, it is unfortunate that many of the discussions we have had 
on the mailing list have not been incorporated by the design team.

Here are some comments:

1.An overview is missing since the various features are only being 
discovered while reading the document.

2.A key question that might interest a reader is the following: what are 
the common points and the main differences with OAuth ?

3.The whole document is "AS centric" while it should also be "RS 
centric". These two concepts have been explained on the mailing list.

4.The document only speaks about "_the_ AS", as if only one AS would 
exist which is obviously not the case.
     The first access made to a RS shall be able to identify which ASs 
are trusted by the RS. In addition, for each trusted AS, the RS should 
be able
     to indicate which access rights are needed to perform every 
operation possible at that stage. For any subsequent stage, the RS may 
also indicate
     which attributes or access rights are needed to perform each 
subsequent operation.

5."API’s documentation" versus "API discovery". Whereas the API’s 
documentation is static and not necessarily up to date or the RC software
     is not necessarily up to date, API discovery provides real time 
information which is necessarily up to date.

There should be an API discovery mechanism for RSs.

     Using an appropriate HTTP OPTIONS request, the RC should be able to 
query the RS in order to know /at any point of time/:

      * the operations that can be done (i.e. which methods are
        available on which data objects), and
      * the access control characteristics associated with each of these
        operations (i.e. which ASs are being trusted by the RS
        and what should be the incorporated into access token(s) in
        terms of attributes types (and optionally attribute values)
        or in terms of capabilities (i.e. permissions granted).

6.The "user consent" phase has been ignored. It should be done at the 
RS. Using information obtained from a RS, a RC should be able
     to select which AS it wants to contact and explicitly agree to 
request the mentioned attributes to that AS. Alternatively, when the 
user consent phase
     is not done at the RS, it shall be done at the AS.

7.The content and the format of access tokens shall not be considered to 
be opaque to the RC so that the RC can inspect it.
     This is a matter of confidence to make sure for the RC (and for the 
user) that no "extra" information has been included by the AS into the 
access token.

8."Resource Owner (RO) : Authorizes the request from the RC to the RS", 
full stop. The RO is associated with a RS, not with an AS.
     The RS can know in advance with attributes or access rights are 
needed to grant a given operation.

9.The model should allow the use of both Access Control Lists and of 
Capabilities Lists.

      * Access control lists contain identifiers of users and/or
        identifiers of users groups or identity claims in relationship
        with an operation.
      * Capabilities lists contains operations granted on services
        within a RC.

As a consequence, access tokens may contain identifiers of users and/or 
identity claims and/or identifiers of users groups and/or capabilities.
     Whereas identifiers of users and/or identifiers of users groups 
and/or identity claims may be managed by an AS independently from RSs,
     this is not the case for capabilities where a RO associated with a 
RS needs to interact with the AS either in advance or in real time
     (which makes such mechanism much more complex).

10.In the case where access control lists are being used, there should 
be a possibility for a RC, for privacy reasons, to hide the identifier
      of the RS to the AS (usually a URL) when requesting an access 
token. A method able to support such feature has been discussed 
extensively on the mailing list.

11.The text states: "Authorization Server (AS)Manages the requested 
delegations for the RO". This is only one of two possibilities.
      The interaction between a RO and an AS should be considered as an 
option. If a RO needs to interact, for privacy reasons, it should 
preferably
       interact with the RS only.

12.The text states: "ResourceA protected API served by the RS and 
accessed by the RC. Access to this resource is delegated by the RO as 
part of the grant process".
The second part of the sentence should be deleted since a RO is not 
necessarily involved in the grant process.

13.The text states: "Resource Client (RC, aka "client")Requests tokens 
from the AS and uses tokens at the RS.
       An instance of the RC software is identified by its key, which 
can be known to the AS prior to the first request".

This is confusing. The key does not necessarily identify an instance of 
the RC software.
       An instance of the RC software uses a binding key which (for 
privacy reasons) should be dynamic but which may alternatively be static.

14.For privacy reasons, calls from an RS to an AS, such as token 
introspection, should be avoided.

15.Section 2 deals with the parameters when making calls from a RC to an 
AS. This section would need to be revisited.
       Hereafter are only some (of many) concerns about the current 
text. The most important is to identify which parameters shall be used
       and may be used when making a call to get an access token.

      The text states: "resourcesDescribes the rights that the RC is 
requesting for one or more access tokens to be used at RS’s.
      Section 2.1". Then after: "Each object contains a "type" property 
that determines the type of API that the RC is calling.
(...)The value of this field is under the control of the AS.

The value of this field should not be under the control of the AS but of 
the RS.

The text states: "actionsThe types of actions the RC will take at the 
RS". This is needed when capabilities are being used but not needed
      for the other cases. Revealing actions to an AS is against the 
user's privacy.

      The text states: "locationsThe location of the RS as an array of 
strings. These strings are typically URIs identifying the location of 
the RS."

It is typically URLs (not URIs) but it may also be /service names/ so 
that an access token can be delegated by a first RS to a second RS
      belonging to the same service without the need for the first RS to 
request another access token.

Denis