Re: [GNAP] Terminology PR

[Denis <[e-mail]>]

Hello Fabien,

The end-user and the RO are two roles.
The case where (as you write) RO=end-user does not exist. The case where 
these two roles are supported by the same entity may exist.
Since the document is supposed to describe operations between roles, I 
don't see the need to use a specific vocabulary for that specific case.
Other comments are below. One of them attempts to explain (in a Note 2), 
the relationship between a RO and an end-user

> Hello Denis,
>
> The part called "current spec" corresponds to the text before the PR, 
> it's just here for reference.
>
> We made the distinction between the end-user and the RO as clear as we 
> could.
> There is indeed a case where we still keep "user", to indicate that 
> the RO=end-user (and tried to make it clear in the text). I don't see 
> an obvious way to change that.
>
> From your comment I don't see why subject would be a problem.
>
> We indeed tried to avoid the embedding of requirements into the 
> definitions.
>
> The rest of my comments are embedded into your message, and marked 
> with FI for convenience.
>
> Fabien
>
>
> Le lun. 11 janv. 2021 à 16:27, Denis <[e-mail] 
> <mailto:[e-mail]>> a écrit :

>     I have used the text of the wiki to respond.
>
>
>       Latest discussion update
>
>     Here we consolidate the latest proposal(s) from the group. We also
>     include the discussion items (individual feedbacks).
>
>     [Denis] I don't have the feeling that we are converging. There are
>     duplications for some definitions that are spread over the document
>     instead of being grouped together. This does not help to converge.
>
>     We need to clearly separate the role of the "end-user" from the
>     role of a RO. Attempting to collapse these two concepts under the
>     term "user"
>     creates confusion. Attempting to use the term "subject" creates
>     even more confusion.
>
>
>     Trying to incorporate design choices inside the definition section
>     is not appropriate, hence why I propose to remove several notes.
>
>     In my proposals below, I have followed the ISO style for the
>     definitions (a single sentence as short as possible).
>
>
>         Authorization Server (AS)
>
>     server that grants delegated privileges to a particular instance
>     of client software in the form of an access token and other
>     information (such as subject information).
>
>     [Denis]
>
>         Authorization Server (AS):server that grants access privileges
>         to a particular instance of a client software in the form of
>         an access token and provides information about the end user
>
>     Some explanations: In addition to the granting of access tokens,
>     end-users may query the AS about the privileges they store about
>     them.
>
>     We should identify in the main body of the document thse two
>     distinct operations.
>
>
> [FI] so far the type of additional information we would send is 
> specified as subject information, hence its use in the definition.
[Denis] Since a subject is currently defined in the draft as "person, 
organization or device", I don't believe that an AS "grants other other 
information
(such as subject information)" because it does not manage organizations 
nor devices. In the context of an AS, the AS only manages end-user 
information
hence why it is unnecessary to introduce the term "subject".
>
>
>         Client
>
>     application operated by an end-user that consumes resources from
>     one or several RSs, possibly requiring access privileges from one
>     or several ASs.
>
>     Example: a client can be a mobile application, a web application,
>     etc.
>
>     Note: this specification differentiates between a specific
>     instance (the client instance, identified by its unique key) and
>     the software running the instance (the client software). For some
>     kinds of client software, there could be many instances of that
>     software, each instance with a different key.
>
>     [Denis] Change in the Note:
>
>         (the client instance, identified by its unique key)
>
>     into:
>
>         (the client instance, identified by a unique key)
>
>     Some explanations: The key is unique, but may change.
>
>
> [FI] not sure that your proposal changes much the meaning (at any 
> point in time, its key is unique, and yes, it may be changed over time).
[Denis] It does change it. Since it seems you can live with that change, 
this is fine.
>
>
>         Resource Server (RS)
>
>     server that provides operations on protected resources, where
>     operations require a valid access token issued by an AS.
>
>     [Denis] Change into:
>
>         Resource Server (RS) : server that provides operations on
>         resources, where operations on protected resources require
>         a valid access token issued by one or more ASs
>
>     Some explanations: a resource server may also support resources
>     available to the public.
>
> [FI] yes, but we don't really care about public resources (there's no 
> need for a protocol for that). As for "one or more ASs", this seems to 
> embed a requirement (support multiplicity).

[Denis] A RS may support both public and private resources. At the time 
an operation is performed by a client on a resource,
             it is unknown whether that operation is allowed for the 
public or not.

>
>         Resource Owner (RO)
>
>     subject entity that may grant or deny operations on resources it
>     has authority upon.
>
>     Note: the act of granting or denying an operation may be manual
>     (i.e. through an interaction with a physical person) or automatic
>     (i.e. through predefined organizational rules).
>
>     [Denis] Change into:
>
>         Resource Owner (RO): /entity/that may grant or deny operations
>         on resources it has authority upon
>
>     Some explanations: the term "entity" (without the word "subject")
>     is being used which is a very general term: it may or may not be a
>     human being.
>
> [FI] subject is defined as either human or not.

[Denis] No, a subject is currently defined in the draft as "person, 
organization or device". We don't need to use the term "subject".

>
>         End-user
>
>     natural person that operates _/the/_//client instance.
>
>     Note: that natural person may or may not be the same entity as the
>     RO. When it is explicit that the end-user and the RO are the same
>     entity, the generic term user may be used.
>
>
>         [Denis]
>
>
>         Change into:
>
>
>             *End-user*: natural person that operates _/a/_ client instance
>
>     Remove the Note which is confusing.
>
>
> [FI] "a" might indeed be better.
[Denis] Thanks !

> Regarding the note, it seems that you'd rather not have "user" (and 
> the rest is still useful I think).
> This is actually used in other parts of the spec (cf diagrams) to 
> refer to either RO or end-user, undistinctively. What would you use 
> otherwise?

[Denis] The Note should be removed because it leads to confusion. The 
Note considers only the case where the RO is a natural person, however a 
RO may also be a process.
The Note may be adequate when the RO is being defined. In such a case, I 
would propose:

    Resource Owner (RO): /entity/ that may grant or deny operations on
    resources it has authority upon


    Note 1: The act of granting or denying an operation may be automatic
    (i.e. through predefined rules) or manual (i.e. through an
    interaction with a physical person)..


    Note 2: In the later case, the same physical person may support
    simultaneously the role of the RO and the role of the end-user.

>
>         Attribute
>
>     characteristics related to a subject.
>
>     [Denis] Change into:
>
>         Attribute: characteristics related to an end-user
>
> [FI] are we 100% sure we'll never send anything else?

[Denis] See the discussion above for the reason for not using the term 
"subject".

>
>         Access Token
>
>     a data artifact representing a set of rights and/or attributes.
>
>     Note: an access token can be first issued to an client instance
>     (requiring authorization by the RO) and subsequently rotated.
>
>     [Denis] Remove the Note which has nothing to do in this section.
>
>
> [FI] the note serves the purpose of explaining the lifecycle of an 
> access token, which I believe is useful to the reader. Cf the large 
> littérature about access vs refresh in the oauth2 world.

[Denis] We are in the definition section. Explaining the lifecycle of an 
access token may indeed be very useful
             but a dedicated section in the main body of the document 
would much better address this topic.

>
>         Grant
>
>     (verb): to permit an instance of client software to exercise some
>     set of delegated rights to access a protected resource and/or
>     to receive some attributes at a specific time and during a
>     specific duration. (noun): the act of granting.
>
>     [Denis] Change into:
>
>         *Grant*
>
>         (verb): to receive some attributes from an AS at a specific
>         time and valid for a specific duration and/or
>         to permit an instance of client software to exercise this
>         attributes to perform an operation on a protected resource
>
>         (noun): the act of granting
>
>     Some explanations: The current text identifies two cases. I have
>     switched these two cases.
>
>
> [FI] how is that better?

[Denis] Before being able to use an access token, it is necessary to get 
it. So the proposed definition follows a chronological order.


>         Privilege
>
>     right or attribute associated with a subject.
>
>     [Denis]
>
>         *Privilege*: right or attribute associated with an end-user
>
>     Note: the RO defines and maintains the rights and attributes
>     associated to the protected resource, and might temporarily delegate
>
>     some set of those privileges to an end-user. This process is
>     refered to as privilege delegation.
>
>     [Denis] Remove the Note which is unrelated to the definition.
>
>
> [FI] this is useful to understand what we call "delegated privileges" 
> in the AS definition.

[Denis] Reading the original proposed definition again, the Note 
considers the RO.

I consider that a right is a capability to perform an operation on a 
protected resource. Such capabilities is given by a RO to an end-user.
I consider that an attribute is a characteristics related to an end-user 
(e.g. a name, a group membership)

Privilege = right or attribute associated with an end-user which allows 
to support respectively
                               either a capability scheme or an 
attributed-based access control (ABAC) using ACLs.

A RO maintains rights but it does not maintain attributes.

It might be useful to define in addition:

    *control attributes*: set of attributes associated to a protected
    resource used to control operations on that resource

    Note: a RO defines and maintains the control attributes associated
    to a protected resource

>     Protected Resource
>
>     protected API (Application Programming Interface) served by a RS
>     and that can be accessed by a client, if and only if a valid
>     access token is provided.
>
>     Note: to avoid complex sentences, the specification document may
>     simply refer to resource instead of protected resource.
>
>
>         Right
>
>     ability given to /a subject/ to perform a given operation on a
>     resource under the control of a RS.
>
>     [Denis] Change into:
>
>         *Right*: ability given to /an end-user/ to perform a given
>         operation on a resource under the control of a RS
>
>
> [FI] it's not rights about the end-user per say, it's rights delegated 
> by the RO.
> And so in this context, subject seems a better description and avoids 
> the potential misunderstanding. And least that's the intent.

[Denis]  A right is not given to an organization or to a device, but 
only to an end-user.

>
>         Subject
>
>     person, organization or device.
>
>     [Denis] Remove this definition since this terms is confusing and
>     unnecessary.
>
>
> [FI] I'm not sure what is confusing. This is useful at the bare 
> minimum in context with the next definition.
> I think it can be used as a basic definition for other terms, and 
> that's what is proposed.

[Denis] See the arguments raised above.

>
>         Subject Information
>
>     statement asserted locally by an AS about a subject.
>
>     [Denis] Remove this definition since this terms is confusing and
>     unnecessary.
>
>
> [FI] this is used in the main text, so needs to be defined (or removed 
> from the main text, but that's a different debate).

[Denis] See the arguments raised above.

>
>       Current spec
>
>     Here we find all the terms and definitions from the current
>     version of the draft (01), as a reference.
>
>
>         Roles
>
>
>           Authorization Server (AS)
>
>     Manages the requested delegations for the RO. The AS issues tokens
>     and directly delegated information to the RC.
>     The AS is defined by its grant endpoint, a single URL that accepts
>     a POST request with a JSON payload.
>     The AS could also have other endpoints, including interaction
>     endpoints and user code endpoints, and these are introduced
>     to the RC as needed during the delegation process.
>
>     [Denis] Already discussed above (and far too long for a definition).
>
>
>           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. The AS determines which
>     policies apply to a given RC, including what it can request and on
>     whose behalf.
>
>     **
>
>     **
>
>     [Denis] Already discussed above.
>
>
>           Resource Server (RS, aka "API")
>
>     Accepts tokens from the RC issued by the AS and serves delegated
>     resources on behalf of the RO.
>     There could be multiple RSs protected by the AS that the RC will call.
>
>     [Denis] Already discussed above.
>
>
>           Resource Owner (RO)
>
>     Authorizes the request from the RC to the RS, often interactively
>     at the AS.
>
>     [Denis] Already discussed above.
>
>
>           Requesting Party (RQ, aka "user")
>
>     Operates and interacts with the RC.
>
>     [Denis] Remove. Already discussed above under the term "*end-user"
>
>     *
>
>     *Elements*
>
>
>           Access Token
>
>     A credential representing a set of access rights delegated to the
>     RC. The access token is created by the AS, consumed and verified
>     by the RS,
>     and issued to and carried by the RC. The contents and format of
>     the access token are opaque to the RC.
>
>     [Denis] Already discussed above.
>
>
>           Grant
>
>     The process by which the RC requests and is given delegated access
>     to the RS by the AS through the authority of the RO.
>
>     [Denis] Already discussed above.
>
>
>           Cryptographic Key
>
>     A cryptographic element binding a request to a holder of the key.
>     Access tokens and RC instances can be associated with specific keys.
>
>     [Denis] Change into:
>
>         *Binding key*: a cryptographic key used by a client to bind an
>         access token to a client instance
>
>     Some explanations: cryptographic key is a general term. In the
>     context of GNAP we want that key to achieve a specific function:
>     to *bind *an access token to a client instance.
>
>
>           Resource
>
>     A 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.
>
>     [Denis] We don't need this definition. Already discussed above
>     under the wording" Protected Resource".
>
>
>           Subject Information
>
>     Information about the RO that is returned directly to the RC from
>     the AS without the RC making a separate call to an RS.
>     Access to this information is delegated by the RO as part of the
>     grant process.
>
>     [Denis] We don't need this definition.
>
>     Some explanations: an end-user may wish to know the attributes
>     stored for him by the AS.
>     However, no information needs to be returned to a client about a RO.
>
Denis


>     Denis
>
>>     Hi everyone,
>>
>>     I wish you all a happy new year.
>>
>>     I just created a PR
>>     (https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/155
>>     <https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/155>)
>>     that takes into account the various feedbacks. The automatic
>>     build process is not working, but you can see the diffs and build
>>     the html locally if you prefer. The definitions have also been
>>     updated on the wiki
>>     (https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology
>>     <https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology>)
>>     if you prefer to check there.
>>
>>     Feedbacks welcome before we move to pending merge later on.
>>
>>     Cheers
>>     Fabien
>>
>
>     -- 
>     TXAuth mailing list
>     [e-mail] <mailto:[e-mail]>
>     https://www.ietf.org/mailman/listinfo/txauth
>     <https://www.ietf.org/mailman/listinfo/txauth>
>