Re: [GNAP] Terminology proposal

from the point of view of the GNAP std I would drop typically. If it meets
the std then it MUST get an access token. It is the AS that is optional (at
least i think that is where GNAP is headed.)
Peace ..tom

On Sun, Dec 13, 2020 at 11:21 AM Fabien Imbault <fabien.imbault@gmail.com>
wrote:

> Hi Yaron,
>
> Stylistic comments are very important too. And at some point we'll need a
> review from native english speakers in the group (I'm sure Justin and Aaron
> will be of great help here).
>
> Just wondering: what do you mean by "typically"? (ideally I'd rather have
> a definition which is not dependent on use case).
>
> As soon as we land on something, I'll update the wiki.
>
> Fabien
>
>
>
> On Sun, Dec 13, 2020 at 8:12 PM Yaron Sheffer <yaronf.ietf@gmail.com>
> wrote:
>
>> It’s purely stylistic, but I find the definition of RS (“server that
>> denies operations”) a bit funny. How about:
>>
>>
>> Resource Server (RS)
>>
>>    - Definition: server that provides operations on protected resources;
>>    such operations typically require that the client provide valid access
>>    tokens issued by an AS
>>
>> Thanks,
>>
>>                 Yaron
>>
>>
>>
>> *From: *Fabien Imbault <fabien.imbault@gmail.com>
>> *Date: *Sunday, December 13, 2020 at 13:20
>> *To: *Yaron Sheffer <yaronf.ietf@gmail.com>
>> *Cc: *Denis <denis.ietf@free.fr>, GNAP Mailing List <txauth@ietf.org>
>> *Subject: *Re: [GNAP] Terminology proposal
>>
>>
>>
>> Hello everyone,
>>
>>
>>
>> We're at the end of the 2 week period, and so I integrated the various
>> feedbacks :
>>
>>
>>
>> a) from Yaron's feedback, removed new term "IS" and update issue
>> https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/133 to handle
>> the proposal here
>>
>> b) integrated Tom's feedback regarding the RO (and moved  to access token)
>>
>> c) definitions follow an ISO style as suggested by Denis, which we took
>> as a starting point (but I made the modifications I felt were necessary)
>>
>>
>>
>> I modified the definitions, notes and examples as a consequence. You'll
>> also find a summary of discussions for each term, so that we can keep track
>> of them too.
>>
>>
>>
>> My biggest question is : what should we use as our main vocabulary
>> between privilege/rights/attribute? I tried to clarify, please let me know
>> what you think. The general idea is that we grant privileges that are
>> delivered under the form of access tokens (which contain rights and/or
>> attributes).
>>
>> Regarding whether access tokens should be opaque or not, I suggest to
>> remove that from the definition and handle that in issue
>> https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/145
>>
>>
>>
>> All has been consolidated on the wiki too
>> https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology so
>> that we have a clearer view of where we stand.
>>
>>
>>
>> Please comment further on the list if you have comments, I'll update if
>> necessary (and refer to the mailing list url in the comment of the wiki
>> update, from now on). Then editors will review the proposal.
>>
>> Here is a copy of
>> https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology#latest-discussion-update
>> .
>>
>>
>> Latest discussion update
>>
>> Here we consolidate the latest proposal(s) from the group. We also
>> include the discussion items (individual feedbacks).
>> 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
>>
>> Feedbacks / discussion / questions :
>>
>>    - Suggested "privilege" definition (that we would probably add as an
>>    additional sub-entry): "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>
>>    - Note that we don't include claims in the definition (cf OIDC/SSI
>>    integration), but since we talk about a "particular end-user" it is assumed
>>    somehow
>>    - Denis suggested we used "rights and attributes" instead of
>>    privileges. [FI] However i don't think one can really speak about granting
>>    attributes, except indirectly (ABAC). See access token for more on that,
>>    where we can be more specific.
>>    - Do we allow cases such as distributing the AS on a mobile? (in this
>>    case we're at the limit of what we call a server)
>>
>> Client
>>
>>    - Definition: application used by an end-user to interact with an AS
>>    or a RS
>>    - 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.
>>
>> Feedbacks / discussion :
>>
>>    - Replaces previously proposed RC, we wouldn't provide a short name.
>>    - Keep OAuth2 term, but we clarify it
>>    - Further discussion on Client instance
>>    <https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/132>
>>
>> Resource Server (RS)
>>
>>    - Definition: server that denies operations on protected resources,
>>    unless the client provides valid access tokens issued by an AS
>>
>> Feedbacks / discussion :
>>
>>    - Denis suggests to make explicit that we could have several ASs -
>>    "issued by one or more ASs" (also we'd need a convention on how to denote
>>    plural, e.g. ASs). Not exactly sure right now of the multiple issuance
>>    would work, so needs to be clarified. Also not sure if that's even
>>    necessary (do we lack in generality if we keep the singular?)
>>
>> Resource Owner (RO)
>>
>>    - Definition: physical person acting on its own or representing an
>>    organization, that may grant privileges on resources he has authority upon
>>    - Note: the act of granting privileges may be manual (i.e. through an
>>    interaction) or automatic (i.e. through predefined rules).
>>
>> Feedbacks / discussion
>>
>>    - As some point we suggested "The RO may decide to remove its consent
>>    at any time." Tom provided useful feedback
>>    <https://mailarchive.ietf.org/arch/msg/txauth/n_vDfQGaUO6v56nbXyG5lpDda-M/> on
>>    that. Moved to access token where it fits more naturally.
>>
>> End-user
>>
>>    - Definition: physical person that operates with the client software
>>    - Note: that physical person may or may not be the same entity as the
>>    RO
>>
>> 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)
>>
>> Feedbacks / discussion
>>
>>    - Would require the subdefinitions right: ability for an end-user to
>>    perform a given operation (or action) on a resource (or object) under the
>>    control of a RS / attribute: property related to an end-user.
>>    - Note 2 is here in relationship with PR 129
>>    <https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/129>
>>
>> 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
>>
>> Key
>>
>>    - Definition: public cryptographic binding a request to the holder of
>>    a private key, used by the protocol entities (AS, RS, client instance,
>>    bound token, etc.) to identify themselves.
>>    - Note: a key can be rotated or revoked by its holder. The protocol
>>    supports the update of the key information.
>>
>> Feedbacks / discussion
>>
>>    - Denis thinks the term "key" is well understood and doesn't need to
>>    be defined. Yet, I tend to believe we'd gain to keep it. First the generic
>>    term "key" may be many things : symmetric/asymmetric, public/private, etc.
>>    It's also useful to explain its use in the protocol
>>
>> Resource
>>
>>    - Definition: protected API served by a RS and accessed by a client,
>>    if and only if a valid access token is provided
>>
>>
>>
>> On Fri, Dec 11, 2020 at 6:05 PM Fabien Imbault <fabien.imbault@gmail.com>
>> wrote:
>>
>> Hi Yaron,
>>
>>
>>
>> Yes I highlighted that this was a new term. We can deal with it as a
>> separate issue indeed.
>>
>>
>>
>> Best
>>
>> Fabien
>>
>>
>>
>> On Fri, Dec 11, 2020 at 6:02 PM Yaron Sheffer <yaronf.ietf@gmail.com>
>> wrote:
>>
>> Hi Fabien,
>>
>>
>>
>> Yes, we definitely need to reach closure on terminology, thank you for
>> driving this discussion!
>>
>>
>>
>> One process comment: unless I’m missing something, the Interact (or
>> Interaction) Server is not mentioned in the current draft. I suggest we do
>> not introduce new functional components or new behaviors as part of the
>> terminology discussion. Specifically, if the IS is useful, let’s reach
>> consensus on that separately. Then we can add it into the Terminology
>> section.
>>
>>
>>
>> Thanks,
>>
>>                 Yaron
>>
>>
>>
>> *From: *TXAuth <txauth-bounces@ietf.org> on behalf of Fabien Imbault <
>> fabien.imbault@gmail.com>
>> *Date: *Friday, December 11, 2020 at 14:31
>> *To: *Denis <denis.ietf@free.fr>
>> *Cc: *GNAP Mailing List <txauth@ietf.org>
>> *Subject: *Re: [GNAP] Terminology proposal
>>
>>
>>
>> Hi Denis,
>>
>>
>>
>> Thanks for your detailed feedback. My comments are embedded into your
>> message. Again those comments are my own, and we'll need to converge to
>> some consensus beyond what I say here. My main open question is really
>> about the RO being optional. Could you explain?
>>
>>
>>
>> Fabien
>>
>>
>>
>> On Fri, Dec 11, 2020 at 12:08 PM Denis <denis.ietf@free.fr> wrote:
>>
>> This is a global response to the definitions proposal.
>>
>>
>> TerminologyI propose to adopt the way ISO defines how to write the
>> definitions.It is a *single sentence* that may be substituted to the
>> wording being defined in the context of a sentence that uses that
>> definition.
>> Since this single sentence can be substituted to the wording, there is
>> not point at the end of that sentence. The sentence does not
>> have a "a" or "the" in front of it.
>>
>>
>>
>> [FI] In the first version, I was mostly trying to not get too far away
>> from the current text. But yes that's a good idea, it gives a more
>> formal rule, which has been proven to work.
>>
>>
>>
>> If more information is useful to understand the wording, it is placed in
>> one or more notes afterwards.
>>
>>
>>
>> Note: The ISO rules for drafting definitions are in the ISO/IEC
>> Directives, Part 2 (edition 2018):
>>
>> 16.5.6    Definitions
>>
>> The definition shall be written in such a form that it can replace the
>> term in its context. It shall not start with an article (“the”, “a”) nor
>> end with a full stop.
>> A definition shall not take the form of, or contain, a requirement.
>>
>> Only one definition per terminological entry is allowed. If a term is
>> used to define more than one concept, a separate terminological entry shall
>> be created
>> for each concept and the domain shall be included in angle brackets
>> before the definition.
>>
>> Circular definitions, which repeat the term being defined, are not
>> allowed.
>>
>> Comments are inserted between the lines.
>>
>>
>>
>> Hello everyone,
>>
>>
>>
>> As an editor : a quick reminder that terminology issues will be discussed
>> in the coming weeks, and we're expecting your inputs right now (according
>> to the process previously sent on the mailing list).
>>
>> https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/29
>>
>> https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology
>>
>>
>>
>> The rest of this message is a proposal written in my own name, and
>> doesn't involve discussions with the editors/chairs who might have
>> different opinions.
>> Authorization Server (AS)
>>
>> Manages the granting of privileges to a third-party client instance. If
>> the RO consents to at least a part of what is requested, the AS issues an
>> access token to the client.
>>
>> *My questions: *
>>
>> *- was else do we issue? (e.g. id claims, payment info, etc.) We could
>> have more than access tokens, but “directed information” is not clear. I
>> removed that for now.*
>>
>> *- there might potentially be several AS, currently we don’t reflect that
>> anywhere. If would leave that as an open item, depending on what we end up
>> doing in the spec*
>>
>> I am not in favour of this definition: A RO as defined later: "authorizes
>> the request to access a protected resource from the RS to the client".
>> This does not mean in any way that a RO has necessarily a direct
>> relationship with one or more ASs. [FI] indeed we could remove that
>> limitation, to have a more general definition
>> Using the ISO style for definitions, I propose:
>>
>> Authorization Server (AS): server that grants rights and/or attributes to
>> a particular end-user and that provides them to a client in the form of an
>> access token
>>
>> Since this definition is using the words "rights" and "attributes",
>> these two terms need to be defined as well.
>>
>> right: ability for an end-user to perform a given operation on an object
>> under the control of a RS
>>
>> attribute: property related to an end-user
>>
>>
>>
>> [FI] I like your proposal in general. There might be some discussions on
>> the details. I don't think it makes sense to grant "attributes".
>>
>> Some explanations: a "right" is able to support a capability scheme. An
>> "attribute" is able to support an ACL scheme.
>>
>> These two schemes are able to support "discretionary access control"
>> where the end-user has a "need-to-know".
>>
>> However, some attributes are also able to support what  was called in the
>> past "mandatory access control"; for example,
>>
>> if the end-user is cleared to "top-secret / marketing strategy".
>>
>>
>>
>> Interact Server (IS) - this is a new proposed term
>>
>> Manages the front-end interaction with the RO, in order to gather its
>> consent. Depending on the deployment model and the privacy requirements,
>> the IS may be a component of the AS, or may be distinct and managed by
>> another party.
>>
>> Example : an IS usually involves a web interface accessed by RO through a
>> web browser.
>>
>> Note : an IS is not always required, especially if the access is granted
>> through automated policies.
>>
>> Using the ISO style for definitions, I propose:
>>
>>
>>
>> Interact*ion* Server (IS)
>>
>> component from the AS or server interfacing with an AS that manages the
>> interactions with a RO, in order to gather its authorizationNote : since
>> the RO is an optional component, the IS is also an optional component.
>>
>>
>>
>> [FI] indeed IS is optional. note for myself when looking at RO : why is
>> RO optional ?
>>
>> Client Requests privileges from the AS, and uses access tokens at the
>> RS. This specification differentiates between a specific instance (the
>> client instance, identified by its unique 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.
>> The AS determines which policies apply to a given client instance,
>> including what it can request and on whose behalf.
>>
>> Some comments: The above text is stating: "(the client instance,
>> identified by its unique public key)".
>> A client instance may use a public key, but that key is not necessarily
>> unique, in particular when there are multiple ASs.
>>
>> [FI] yes, although when possible I would still consider a better practice
>> to expose a key to a specific AS and not to the entire set of available
>> ASs.
>>
>> Example : a client can be a mobile application or a web application (the
>> client software) that requires authorizations from the RO to retrieve
>> content from various protected APIs. The client instance may for instance
>> refer to a specific version of that client software.
>>
>> *See on-going discussion :
>> https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/132
>> <https://github.com/ietf-wg-gnap/gnap-core-protocol/pull/132> (client
>> instance). *
>>
>> Using the ISO style for definitions, I propose:
>>
>> Client: application used by an end-user to interact with an AS or a RS
>>
>> Note: a client can be a mobile application or a web application [FI] for
>> me those are just examples, because there could me more (ex IoT device)
>>
>> [FI] you remove the entire discussion on client instance / client
>> software, is that on purpose because you think it's not useful/right, or is
>> it because of something else? (maybe add your comment of the related
>> issue)
>>
>> Resource Server (RS)
>>
>> Accepts valid access tokens from the client issued by the AS and serves
>> protected resources on behalf of the RO. There could be multiple RSs
>> protected by the AS that the client may call.
>>
>> Example : a RS is often composed of protected APIs that can be consumed
>> by authorized client software.
>>
>> One comment: a RO is not necessarily involved. [FI] a bit hard to
>> imagine, there's some kind of owner. Could you be more explicit?
>> Using the ISO style for definitions, I propose:
>>
>> Resource Server (RS): server that accepts valid access tokens from
>> clients issued by one or more ASs which are used to grant or deny some
>> requested operations
>>
>> Note: a RS is often composed of protected APIs that can be consumed by
>> clients.
>>
>>
>>
>> Resource Owner (RO)
>>
>> Authorizes the request to access a protected resource from the RS to the
>> client. The RO may decide to remove its consent at any time.
>>
>> Note : the RO may be a physical person or may represent an organization.
>>
>>
>>
>> Two comments: In order to avoid confusion with the end-user consent, the
>> word " authorization" is being used instead of "consent". [FI] ok
>>
>> It should be said that the RO is an optional component. [FI] why? Using
>> the ISO style for definitions, I propose:
>>
>> Resource Owner (RO): physical person acting on its own or representing an
>> organization that authorizes to clients operations on protected resources
>> from a RS
>>
>> Note: The RO is an optional component that may interact either with one
>> RS or with one or more ASs ,e.g. using an IS.
>>
>> End-user – this was previously Requesting Party RQ
>>
>> A physical person that operates and interacts with the client software.
>>
>> Note : the end-user may or may not be the same entity as the RO.
>>
>> The Note is slightly incorrect. the *physical person* may or may not be
>> the same entity as the RO. [FI] I didn't understand your comment
>> Using the ISO style for definitions, I propose:
>>
>> End-user :  physical person that operates and interacts with the client
>> software
>>
>> Note : that physical person may or may not be the same entity as the RO.
>>
>>
>>
>> Access Token
>>
>> A set of privileges delegated to the client instance for a specific
>> end-user. An access token is created by the AS, consumed and verified by
>> the RS, and issued to and carried by the client's end-user on behalf of the
>> RO. The contents and format of the access token are opaque to the client.
>>
>> Example : JWT is a commonly used format.
>>
>> Note 1 : an access token generally has a limited duration, after which it
>> may be refreshed at a regular interval.
>>
>> Note 2 : an access token may be revoked at any time by the RO.
>>
>> Note 3 : an access token may act as a capability or require an additional
>> authentication by binding to a key
>>
>> A fundamental point: the third sentence from the definition states: "The
>> contents and format of the access token are opaque to the client".
>>
>> [FI] I'll check your other thread dedicated to that issue
>>
>> See my other email sent today about "RS-Token Introspection or RC-Token
>> Introspection" where I conclude:
>>
>>       For end-users caring about their privacy (or for systems willing to
>> protect the user's privacy), access tokens should not be considered
>>       to be opaque to RCs nor to RSs and ASs should not support Token
>> Introspection, whether it is RS-Token Introspection or RC-Token
>> Introspection.
>>
>> The example and the other Notes above should be removed. If needed they
>> should be placed in the main body of the document.
>>
>> Using the ISO style for definitions, I propose:
>>
>> Access Token : digitally signed data issued by an Authorization Server
>> (AS) and consumed by a Resource Server (RS)
>>                          that contains rights and/or attributes granted
>> to a particular end-user
>>
>>
>>
>> Grant
>>
>> The process by which the client requests and is given delegated access to
>> the RS by the AS through the authority of the RO.
>>
>> Using the ISO style for definitions, I propose:
>>
>> Grant: permission given to end-user to use a subset of his rights and/or
>> his attributes at a specific time and for a specific duration
>>
>>
>>
>> Key
>>
>> A public cryptographic binding a request to the holder of a private key.
>> Access tokens and client instances can be associated with specific keys at
>> a point in time.
>>
>> Note : a key can be rotated or revoked by its holder. The protocol
>> supports the update of the key information.
>>
>> "key" is a general term that is well understood and that does not need to
>> be defined. [FI] I really wouldn't bet on that. We can reuse an existing
>> definition but it is a central piece so we need to be explicit
>>
>> The "definitions" section is not intended to explain what can be done
>> with the term that is being defined. [FI] ok we can work on that
>> Until the word "key" is qualified using one or more other terms, this
>> definition should be removed.
>>
>>
>>
>> Resource
>>
>> A protected API served by the RS and accessed by the client if and only
>> if access has been granted. Access to this resource is delegated by the RO
>> as part of the grant process.
>>
>> The second sentence of the definition is not in accordance with the ISO
>> style or definitions and furthermore this second sentence should be removed
>> since a RO is an optional element.
>>
>>
>> Using the ISO style for definitions, I propose:
>>
>> Resource: protected API served by a RS and accessed by a client, if and
>> only if access is granted by an access token
>>
>> Subject Information
>>
>> Information about a subject (usually a RO) that is returned directly to
>> the client from the AS.
>>
>> Note : this information needs to be unique.
>>
>>
>>
>> This definition exhibits several problems:
>>
>> (1) The term "subject" is not defined.
>>
>> (2) The information that is returned is for an end-user, i.e. not for "(usually
>> a RO)".
>>
>> (3) The Note states : "this information needs to be unique". Does it mean
>> unique for the AS ? globally unique ?
>>
>> This definition should be revisited. [FI] I agree (I myself had many
>> questions here)
>>
>> Denis
>>
>>
>>
>> *My questions : *
>>
>> *- probably we’d need to define subject*
>>
>> *Subject :
>> https://open-measure.atlassian.net/wiki/spaces/DIC/pages/67600697/Subject+Dictionary+Entry
>> <https://open-measure.atlassian.net/wiki/spaces/DIC/pages/67600697/Subject+Dictionary+Entry>*
>>
>> *- might be useful to clarify the relationship to what identity providers
>> do *
>>
>>
>>
>>
>>
>> Cheers
>>
>> Fabien
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> --
>> TXAuth mailing list
>> TXAuth@ietf.org
>> https://www.ietf.org/mailman/listinfo/txauth
>>
>> -- TXAuth mailing list TXAuth@ietf.org
>> https://www.ietf.org/mailman/listinfo/txauth
>>
>> --
> TXAuth mailing list
> TXAuth@ietf.org
> https://www.ietf.org/mailman/listinfo/txauth
>