[GNAP] Comments on the GNAP Wiki Terminology

[Denis <[e-mail]>]

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 theabove 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
      <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