Subject: [GNAP] Terminology PR

From: Fabien Imbault <[email-masked]>
Date: Tue, 5 Jan 2021 14:04:01 +0100

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) 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) if you
prefer to check there.

Feedbacks welcome before we move to pending merge later on.

Cheers
Fabien

---

From: Mark Lizar <[email-masked]>
Date: Tue, 5 Jan 2021 19:38:21 +0000

Hi Fabien,  et al,

Great start!!

Could you clarify the use and application of the term subject, as the term is used in some legal standards for semantics and I wonder if this is related to the legal semantic attribution of data subject.

In the glossary,  it also seems the Subject Entity is referring to what is commonly know as legal entity.   And the term subject can refer to a few things at this technical level.— e.g.  a semantic term referencing in general the topic of the resource  or is it the legal entity / credential that corresponds to the accountable controller of a resource ?

- Mark

On 5 Jan 2021, at 08:04, Fabien Imbault <[email-masked]<mailto:[email-masked]>> wrote:

Hi everyone,

I just created a PR (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) if you prefer to check there.

Cheers
Fabien
--
TXAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/txauth

---

From: Fabien Imbault <[email-masked]>
Date: Wed, 6 Jan 2021 14:20:26 +0100

Hi Mark,

Thanks for the feedback.

The original requirement for "subject" comes from the reference to
https://tools.ietf.org/html/draft-ietf-secevent-subject-identifiers-06
(used in the main text). The objective was to try to avoid various terms
which are synonyms.

You're right, it's close to a legal entity, except from the fact that it is
defined more broadly (person, organization or device), which is something
we can encounter for the RO for instance.

For instance we had previous discussions where the RO was defined as :
"personal or organizational entity"
which I replaced in the latest draft by
"subject entity" (since it is defined)

For "Subject Information", the question whether this refers to the end-user
or the RO is currently left open.

Please let me know your thoughts.

Cheers
Fabien

On Tue, Jan 5, 2021 at 8:38 PM Mark Lizar <[email-masked]> wrote:

> Hi Fabien,  et al,
>
> Great start!!
>
> Could you clarify the use and application of the term subject, as the term
> is used in some legal standards for semantics and I wonder if this is
> related to the legal semantic attribution of data subject.
>
> In the glossary,  it also seems the Subject Entity is referring to what is
> commonly know as legal entity.   And the term subject can refer to a few
> things at this technical level.— e.g.  a semantic term referencing in
> general the *topic* of the resource  or is it the* legal entity
> / credential *that corresponds to the accountable controller of a
> resource ?
>
> - Mark
>
> On 5 Jan 2021, at 08:04, Fabien Imbault <[email-masked]> wrote:
>
> Hi everyone,
>
> https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology) if
> you prefer to check there.
>
> [email-masked]

---

From: Fabien Imbault <[email-masked]>
Date: Wed, 6 Jan 2021 17:01:38 +0100

Hi everyone,

I've committed some changes (based on the useful comments made on the PR,
from Justin), visible in the PR itself or on the wiki.

Cheers
Fabien

The generation of the html doesn't work on a forked project, because the
netlify token doesn't match.

On Wed, Jan 6, 2021 at 2:20 PM Fabien Imbault <[email-masked]>
wrote:

> You're right, it's close to a legal entity, except from the fact that it
> is defined more broadly (person, organization or device), which is
> something we can encounter for the RO for instance.
>
> For "Subject Information", the question whether this refers to the
> end-user or the RO is currently left open.
>
>> Could you clarify the use and application of the term subject, as the
>> term is used in some legal standards for semantics and I wonder if this is
>> In the glossary,  it also seems the Subject Entity is referring to what
>> is commonly know as legal entity.   And the term subject can refer to a few

---

From: Tom Jones <[email-masked]>
Date: Wed, 6 Jan 2021 13:27:16 -0800

Right - the correct term should be *subjects' information* as there are
potentially two subjects, the RO and the "end-user" (really terribly
confusing name). If you consider the case where the end-user is the parent
of a child, or of their spouse, both subjects will be asked to supply
information in order to be authenticated.
Peace ..tom

---

From: Adrian Gropper <[email-masked]>
Date: Wed, 6 Jan 2021 16:51:50 -0500

I'm new to the GNAP list so please forgive me as I get up to speed.

RO is a role and the 'subject' of a piece of data is not. I don't see any
problem in keeping this distinction straight throughout the spec.

- Adrian

---

From: Tom Jones <[email-masked]>
Date: Wed, 6 Jan 2021 14:07:49 -0800

you miss the point.  There can be more than one subject and more that one
collection of subject data.
Peace ..tom

On Wed, Jan 6, 2021 at 1:52 PM Adrian Gropper <[email-masked]>
wrote:

>>>> 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
>>>> https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology)
>>>> if you prefer to check there.
>>>>

---

From: Fabien Imbault <[email-masked]>
Date: Wed, 6 Jan 2021 23:14:13 +0100

Adrian, welcome, always happy to see new people coming in.

Tom, I agree this is a possibility but do we need that in the definition
itself (for a somewhat specific use case)? I don't see any loss of
generality in the current proposal.

On Wed, Jan 6, 2021 at 11:08 PM Tom Jones <[email-masked]>
wrote:

>>>> You're right, it's close to a legal entity, except from the fact that
>>>> it is defined more broadly (person, organization or device), which is
>>>>> In the glossary,  it also seems the Subject Entity is referring to
>>>>> what is commonly know as legal entity.   And the term subject can refer to
>>>>> a few things at this technical level.— e.g.  a semantic term referencing in

---

From: Tom Jones <[email-masked]>
Date: Wed, 6 Jan 2021 14:16:02 -0800

you yourself brought up the problem. We do not know that the term "subject
data" refers to.  My suggestion is to make subject plural.
Peace ..tom

On Wed, Jan 6, 2021 at 2:14 PM Fabien Imbault <[email-masked]>
wrote:

>>> RO is a role and the 'subject' of a piece of data is not. I don't see
>>> any problem in keeping this distinction straight throughout the spec.
>>>
>>> - Adrian
>>>
>>>> Right - the correct term should be *subjects' information* as there
>>>> are potentially two subjects, the RO and the "end-user" (really terribly

---

From: Fabien Imbault <[email-masked]>
Date: Wed, 6 Jan 2021 23:19:56 +0100

I don't think I spoke about subject data. I did speak about subject, as an
alternative to using either person/org/device.

We also already have subject information. Which is just really defined as a
statement about the subject. Is that what you call subject data here?

Le mer. 6 janv. 2021 à 23:16, Tom Jones <[email-masked]> a
écrit :

>>> you miss the point.  There can be more than one subject and more that
>>> one collection of subject data.
>>> Peace ..tom
>>>
>>>
>>>>> On Wed, Jan 6, 2021 at 5:20 AM Fabien Imbault <
>>>>> [email-masked]> wrote:
>>>>>
>>>>>> Hi Mark,
>>>>>>
>>>>>> Thanks for the feedback.
>>>>>>
>>>>>>> Could you clarify the use and application of the term subject, as
>>>>>>> the term is used in some legal standards for semantics and I wonder if this
>>>>>>> is related to the legal semantic attribution of data subject.
>>>>>>>

---

From: Denis <[email-masked]>
Date: Mon, 11 Jan 2021 16:26:53 +0100

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.

    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.

    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.

    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.

    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.

    Attribute

characteristics related to a subject.

[Denis] Change into:

    Attribute: characteristics related to an end-user

    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.

    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.

    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.

    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

    Subject

person, organization or device.

[Denis] Remove this definition since this terms is confusing and 
unnecessary.

    Subject Information

statement asserted locally by an AS about a subject.

[Denis] Remove this definition since this terms is confusing and 
unnecessary.

  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

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

---

From: Fabien Imbault <[email-masked]>
Date: Mon, 11 Jan 2021 18:28:20 +0100

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 <[email-masked]> 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).
>
>
>
> 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.
>
>
>
> 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.
>

[FI] so far the type of additional information we would send is specified
as subject information, hence its use in the definition.

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

[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)

>  Some explanations: a resource server may also support resources
[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).

> 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
[FI] subject is defined as either human or not.

> End-user
>
> natural person that operates *the* client instance.
>
>
>
> 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
>

[FI] "a" might indeed be better.
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?

> [FI] are we 100% sure we'll never send anything else?

> Note: an access token can be first issued to an client instance (requiring
> authorization by the RO) and subsequently rotated.
>
>
>

[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.

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

[FI] how is that better?

> some set of those privileges to an end-user. This process is refered to as
> privilege delegation.
>
>
>

[FI] this is useful to understand what we call "delegated privileges" in
the AS definition.

>
> 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.
>
>
>
> ability given to *a subject* to perform a given operation on a resource
> *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] Remove this definition since this terms is confusing and

[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] Remove this definition since this terms is confusing and

[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).

> 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)
>
> The AS is defined by its grant endpoint, a single URL that accepts a POST
> request with a JSON payload.
> 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
> Accepts tokens from the RC issued by the AS and serves delegated resources
> on behalf of the RO.
> [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.
>
>
>
> The process by which the RC requests and is given delegated access to the
> RS by the AS through the authority of the RO.
>
>
>
> *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:
> Some explanations: an end-user may wish to know the attributes stored for
> him by the AS.

---

From: Denis <[email-masked]>
Date: Tue, 12 Jan 2021 16:29:13 +0100

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.
>
> 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.
>
> 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 <[email-masked] 
> <mailto:[email-masked]>> a écrit :

>     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).
>
>
>     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
>
>     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.
>
>     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.
>
> [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
> [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.
>

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

>     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:
>
>
[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.

> [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".

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

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

>     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.
>
> [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.

> [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.

> [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
>
>
>     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
>     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.
>
>     **
>
>     **
>
>     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.
>
>     The process by which the RC requests and is given delegated access
>     to the RS by the AS through the authority of the RO.
>
>     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:
>
>     Some explanations: cryptographic key is a general term. In the
>     context of GNAP we want that key to achieve a specific function:
>     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.
>
>     Some explanations: an end-user may wish to know the attributes
>     stored for him by the AS.
Denis

>>     <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
>     [email-masked] <mailto:[email-masked]>
>     <https://www.ietf.org/mailman/listinfo/txauth>
>

---

From: Fabien Imbault <[email-masked]>
Date: Tue, 12 Jan 2021 16:55:10 +0100

Hi Denis,

We could try to remove the term "user" and systematically list RO and
end-user instead. It's not a critical term and is used for convenience (cf
for instance diagram in section 1.4.1, where we have a part labelled "RO +
RQ (User)" in version 3 of the draft, and we have the accompanying text
that explains it too).

I have noted the small change in the end-user definition ("a"), which would
be an update to the PR.

Other comments embed with [FI] in red. Most of them are related to the use
of "subject", which I still find more accurate than RO or end-user in the
general case (that is without being specific about one particular use case
or without embedding requirements in the definition). As previously
mentioned, this also comes from the use of "subject entity" in relationship
to https://tools.ietf.org/html/draft-ietf-secevent-subject-identifiers-06 (used
in the main text), so that we don't use different synonyms in the
definitions. Same answer as what Mark asked for earlier.

Cheers
Fabien

On Tue, Jan 12, 2021 at 4:29 PM Denis <[email-masked]> wrote:

>> client software in the form of an access token and other information (such
>> as subject information).
>>
>>
>>
>> [Denis]
>>

[FI] In most cases, it will be only about the end-user and its access
token. But regarding the use of subject and whether we could send other
information such as subject information, this would be the case if we
include client posture (which is something planned).

> time, its key is unique, and yes, it may be changed over time).
>
>             it is unknown whether that operation is allowed for the public
> or not.
>
[FI] yes indeed the RS may support public or private resources, but the RS
definition still seems valid

> organization or device". We don't need to use the term "subject".
[FI] sorry, I don't get your point. Entity alone doesn't make me understand
it can also be a human.

> [FI] "a" might indeed be better.
[FI] will update the PR

> 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.
> 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)..
>
>             but a dedicated section in the main body of the document would
> much better address this topic.
>
[FI] we could do that too. As any note, it's not critical anyway. It's here
mostly for convenience, but if we feel it's better in the main text, so be
it.

> it. So the proposed definition follows a chronological order.
[FI] ok clearer now, thanks.

> [Denis] Reading the original proposed definition again, the Note considers
> the RO.
>
[FI] it's not easy to describe. It considers the RO and its delegation.

>             Privilege = right or attribute associated with an end-user
> which allows to support respectively
[FI] which is why subject is more general, and can accomodate both use
cases. Anyway, the exact requirement should be left to the main text.

> Note: a RO defines and maintains the control attributes associated to a
> protected resource
>
> [FI] we'll try to really limit new definitions to the bare minimum. So if
we see that's useful, we'll include it. But so far I don't think that adds
much.

>> *Right*: ability given to *an end-user* to perform a given operation on
>> a resource under the control of a RS
>>
>>
> 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.
>
[FI] not always. Could have an automated policy, which assigns rights to
user groups, which is an organizational construct. Device policies might
matter too.
Of course at runtime, it ends up being consumed by an end-user.

---

From: Fabien Imbault <[email-masked]>
Date: Wed, 13 Jan 2021 17:19:27 +0100

Hi Denis,

Thanks to your feedback, I've committed the 3 changes to the PR, which is
the basis for merge.

>From the discussion, "subject" seems the most viable option, as explained
in the previous thread. At least it is consistent and doesn't imply a
specific use case, and if we find better later on we can still improve it
then. And also merging it now enables more surgical changes with dedicated
issue (without the risk of breaking what we improved), instead of a very
broad meta issue 29 (which will be closed).

For the new proposed term (controlled attribute), this should follow the
same process as other potential additions (which we'll try to limit to the
bare minimum), by entering a new dedicated issue. Could you reexplain why
you think that is useful ? (you started during the call but it's better to
have the time to think about it).

Likewise, we have potential discussion for :
- Interaction server (as an optional component dedicated to front end
interaction)
- Key proof (or more precisely key proof of possession)

Each time it will be submitted to the WG for consensus call.

So as a summary :
- most updates from the mailing list and the git have been included
- PR #155 is merged and terminology issue #29 is closed
- please consider using new dedicated issues on that topic

Fabien

On Tue, Jan 12, 2021 at 4:55 PM Fabien Imbault <[email-masked]>
wrote:

> I have noted the small change in the end-user definition ("a"), which
> would be an update to the PR.
>
>> The rest of my comments are embedded into your message, and marked with
>> FI for convenience.
>>
>> Fabien
>>
>>
>> [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).
>>
> [FI] sorry, I don't get your point. Entity alone doesn't make me
> understand it can also be a human.
>
>>
>>
>>> End-user
>>>
>> 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?
>>
>> Note considers only the case where the RO is a natural person, however a RO
>> may also be a process.
>> (i.e. through predefined rules) or manual (i.e. through an interaction
>> with a physical person)..
>>
> [FI] we could do that too. As any note, it's not critical anyway. It's
> here mostly for convenience, but if we feel it's better in the main text,
> so be it.
>
>>
>> Grant
>>>
>> [FI] I'm not sure what is confusing. This is useful at the bare minimum
>> in context with the next definition.