Re: [GNAP] Comments on the GNAP Wiki Terminology

[Fabien Imbault <[e-mail]>]

Well, we need a starting point, and a basic taxonomy is helpful as we can
have a common vocabulary throughout the protocol.
Of course the protocol is the main objective, and we might need to revise
the taxonomy based on what is really specified later on.

I'll prepare a PR so that we can have that initial terminology section and
move forward.

Fabien

On Mon, Dec 21, 2020 at 6:06 PM Tom Jones <[e-mail]>
wrote:

> I tried to warn you about user defined as a role. Perhaps you see why now.
> if the user is a physician, the data is not about the user, it is about the
> patient (the RO, but a RO that doesn't own the data). But it is the
> physician that wants to see the data. Focusing on taxonomy before protocol
> is not helping to make progress.
> Peace ..tom
>
>
> On Fri, Dec 18, 2020 at 9:02 AM Fabien Imbault <[e-mail]>
> wrote:
>
>> Thanks Denis, that's a really useful feedback. I'll review that in more
>> detail, but something that's really not clear to me is the last one,
>> subject information.
>>
>> 1) is it about the end-user ? or the RO ? (as is the current definition
>> in V02)
>> 2) why do we even need to call it subject information ? For instance if
>> it's about the end-user, it should only be end-user information.
>> 3) do we want to use entity or subject in the definitions ? (cf RO for
>> instance). Regarding natural person vs entity we had a discussion on the
>> mailing list previously.
>>
>> Cheers,
>> Fabien
>>
>> On Fri, Dec 18, 2020 at 5:47 PM Denis <[e-mail]> wrote:
>>
>>> FYI, the wiki page is there:
>>> https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology
>>> FYI first, there is a useful web page where you can find all the ISO
>>> definitions as well as the text for any ISO standard (up to its definition
>>> section only):
>>> https://www.iso.org/obp
>>> This may provide some ideas and you will notice that a given term may be
>>> used in different ISO standards with a different definition.
>>>
>>> I have nine comments (each one being numbered).
>>>
>>> * 1) Current definition of AS*:
>>>
>>> The current definition is:
>>>
>>>      *Authorization Server (AS) *
>>>      Definition: server that grants privileges to a particular end-user
>>> and that provides them to a client in the form of an access token
>>> This is fine in general (but see later another comment about it), but
>>> the word privileges is left undefined.
>>>
>>> * 2) Definition of a privilege*
>>> A suggested "privilege" definition has been proposed in the wiki page: "A
>>> privilege is the right to perform an operation (or action) on a Resource."
>>> See also other def
>>> <https://open-measure.atlassian.net/wiki/spaces/DIC/pages/67568310/Privilege+Dictionary+Entry>
>>> .
>>> In the "other def.", the term is considered to be a synonym of a
>>> permission.
>>>
>>> ISO/IEC 29146:2016(en), 3.8 (very long) definition is the following :
>>>
>>>      privilege
>>>     access right
>>>     permission
>>>     authorization to a subject (3.15)
>>> <https://www.iso.org/obp/ui#:term:3.15> to access a resource (3.14)
>>> <https://www.iso.org/obp/ui#:term:3.14>
>>>
>>>     Note 1 to entry: Privilege is a necessary but not sufficient
>>> condition for access. Access occurs when the access request is granted
>>> according to its access control policy.
>>>                               The access control policy is based on
>>> privileges and may include other environmental factors (e.g.
>>> time-of-day, location, etc.)
>>>
>>>     Note 2 to entry: Privileges take the form of data presented by a
>>> subject or obtained for a subject that is used by a Policy Decision Point
>>> in order to grant or deny an operation
>>>                               that a subject is willing to perform on a
>>> resource.
>>> (...)
>>> I propose the following:
>>>
>>>         *privilege*: right or attribute associated with an end-user
>>> with:
>>>         *right*: ability given to an end-user to perform a given
>>> operation on an object under the control of a RS
>>>
>>>       *attribute*: characteristics or property related to an end-user
>>>
>>>
>>>
>>> *3) Definition of a Client * The current definition is:
>>>      *Client *
>>>      Definition: application that consumes resources from one or several
>>> RSs, possibly requiring a negotiation of access privileges with one or
>>> several ASs
>>>
>>>      Note: this specification differentiates between a specific instance
>>> (the client instance, identified by its public key) and the software
>>> running the instance
>>>               (the client software). For some kinds of client software,
>>> there could be many instances of a single piece of client software.
>>>     Example: a client can be a mobile application, a web application,
>>> etc.
>>>
>>> Previously, I proposed:
>>>
>>>       *Client*: application used by an end-user to interact with an AS
>>> or a RS
>>>
>>> The current definition is missing to indicate who is operating the
>>> client. It is an end-user, i.e. it is not another application, nor a
>>> process, nor an entity.
>>> The definition should capture this point.
>>> A second point: the current definition is using the wording "requiring
>>> a negotiation". There is no "negotiation". Either the AS has or has not
>>> the "access privileges".
>>> The words "a negotiation of" should be deleted.
>>>
>>> This raises the point where this definition of a "Client" is using the
>>> wording "*access privileges*" whereas the definition of an
>>> "Authorization Server (AS)"
>>> is using the word "*privileges*". We should make both definitions
>>> consistent. I have a slight preference for "access privileges", but I could
>>> also live with "privileges".
>>>
>>> Hence my proposals:
>>>
>>> *     Client *
>>>      application *operated* *by an end-user *that consumes resources
>>> from one or several RSs, possibly requiring *access privileges from*
>>> one or several ASs
>>>
>>> *    Authorization Server (AS) *
>>>      server that grants *access* privileges to a particular end-user
>>> and that provides them to a client in the form of an access token
>>>
>>>
>>> *4) Definition of a Resource Server (RS) *
>>> The current definition is:
>>>
>>> *     Resource Server (RS) *
>>>      Definition: server that provides operations on *protected *resources;
>>> such operations require that the client provides valid access tokens issued
>>> by an AS
>>> A RS may offer both public resources and protected resources. Valid
>>> access tokens are only needed for protected resources.
>>> I propose the following definition while merging the two sentences:
>>>
>>>       *Resource Server (RS) *
>>>       server that provides operations on resources *where* protected
>>> operations require that the client provides *one or more* valid access
>>> tokens issued by *one or more ASs*
>>> In the  above modification I added "*one or more *". I am presuming
>>> that GNAP will allow the presentation of more that one access token from
>>> different ASs
>>> in order to allow an end-user to perform one operation on a protected
>>> resource.
>>>
>>> *5) Definition of Resource Owner*
>>>
>>> The current definition is:
>>>     * Resource Owner (RO) *
>>>      Definition: personal or organizational entity that may grant
>>> privileges on resources it has authority upon
>>>     Note: the act of granting privileges may be manual (i.e. through an
>>> interaction) or automatic (i.e. through predefined rules).
>>>
>>> I don't know what a "personal entity" is but I know what a "natural
>>> person" is.
>>>
>>> Furthermore, a Resource Owner is not granting privileges (or access
>>> privileges) in the same way an AS is doing.
>>>
>>> It is interesting to take a look at ISO 20078-1:2019(en), 3.1.4 where
>>> Resource Owner (RO) is defined as:
>>>
>>>       responsible party for the Resource(s)
>>>       Note 1 to entry: The Resource Owner is responsible for granting,
>>> denying, and revoking Access to Resource(s).
>>>       Note 2 to entry: The responsible Resource Owner is determined by
>>> the concrete Resource.
>>> I propose:
>>>      *Resource Owner (RO) *
>>>      *natural person *or organizational 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) or automatic (i.e. through predefined rules).
>>>
>>> * 6) Definition of Access Token*
>>> The current definition is:
>>>      Access token
>>>      Definition: digitally signed data that contains specific rights
>>> and/or attributes
>>>     Note 1: the access token can be issued to an end-user (usually
>>> requiring his authentication) and subsequently refreshed.
>>>                 The AS usually provides a method for the RO to revoke
>>> the privileges at any point in time.
>>>     Note 2: an access token may act as a capability (i.e. bearer token)
>>> or require an additional authentication by binding to a key (i.e. bound
>>> token)
>>> The definition is fine, but not the two Notes.
>>> The second sentence from the Note 1 is stating: "The AS usually
>>> provides a method for the RO to revoke the privileges at any point in time".
>>> Revoking "the privileges" is different from revoking an "access token".
>>> The second sentence of this Note 1 which is supposed to be about access
>>> token is confusing.
>>> The privileges may be changed at any point in time using a management
>>> function. Access tokens can be short-lived and thus don't need to be
>>> revoked.
>>> Any call-back from a RS to an AS should be avoided in order to respect
>>> the user's privacy.
>>>
>>> Therefore, I propose to remove the second part of this Note 1 and to
>>> replace "the" by "a" at the beginning of the first sentence.
>>> Note 2 is stating:
>>>       Note 2: an access token may act as a capability (i.e. bearer
>>> token) or require an additional authentication by binding to a key
>>> (i.e. bound token)
>>> From the discussion on the list, I believe that we don't consider bearer
>>> tokens. Note 2 should be removed.
>>> So my proposal is as follows:
>>> *     Access token *
>>>      digitally signed data that contains specific rights and/or
>>> attributes
>>>     Note: an access token can be issued to an end-user (usually
>>> requiring his authentication) and subsequently refreshed.
>>>
>>> * 7) Definition of Grant*
>>> The current definition is:
>>> *     Grant *
>>>      Definition: (verb): to permit, as a privilege given to an end-user
>>> to exercise some rights and/or assert attributes during a specific
>>> duration
>>>     Definition: (noun): the act of granting
>>>
>>> The words ", as a privilege given to" are unnecessary"
>>> I propose:
>>>      Grant
>>>      (verb): to permit an end-user to exercise some rights and/or *to*
>>> assert *some *attributes *at a specific time and *during a specific
>>> duration
>>>     (noun): the act of granting
>>>
>>>
>>> *8) Definition of Resource*
>>> The current definition is:
>>> *     Resource *
>>>       Definition: protected API served by a RS and accessed by a client,
>>> if and only if a valid access token is provided
>>> This definition is incorrect. This definition would be fine for a
>>> Protected Resource. Change it into "Protected Resource":
>>> *     Protected Resource *
>>>      protected API served by a RS and *that can be *accessed by a
>>> client, if and only if a valid access token is provided
>>> If a definition of a Resource is needed, I propose:
>>> *     Resource *
>>>      public or protected resource from a RS
>>>
>>> * 9) Definition of Subject Information *
>>> The current definition is:
>>>
>>> *Subject Information*
>>> Definition: claim asserted locally by an AS about a person,
>>> organization or device
>>> Source:
>>> https://tools.ietf.org/html/draft-ietf-secevent-subject-identifiers-06
>>> (unless we plan to use something specific to GNAP)
>>>
>>> This is information returned by an AS about an end-user.
>>> I would thus simply propose instead:
>>>
>>> *     Subject Information *
>>>      information returned to a Client by an AS about an end-user
>>>
>>> Denis
>>>
>>> --
>>> TXAuth mailing list
>>> [e-mail]
>>> https://www.ietf.org/mailman/listinfo/txauth
>>>
>> --
>> TXAuth mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/txauth
>>
>