Re: [GNAP] Terminology PR

[Fabien Imbault <[e-mail]>]

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.

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

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

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

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

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

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

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

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

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

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

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

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