Re: [GNAP] Terminology PR

[Fabien Imbault <[e-mail]>]

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 <[e-mail]> wrote:

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

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

> 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.
>
[FI] yes indeed the RS may support public or private resources, but the RS
definition still seems valid

>
> 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".
>
[FI] sorry, I don't get your point. Entity alone doesn't make me understand
it can also be a human.

>
>
>> 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 !
>
[FI] will update the PR

>
>
> 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.
>
[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
>>
>> (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.
>
[FI] ok clearer now, thanks.

> 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.
>
[FI] it's not easy to describe. It considers the RO and its delegation.

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

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

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

> 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) 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
>>
>>
>> --
>> TXAuth mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/txauth
>>
>
> --
> TXAuth mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/txauth
>