Re: [GNAP] Terminology proposal

[Fabien Imbault <[e-mail]>]

Thanks Tom. Yes, we now have Yaron's definition, minus the typically.

On Sun, Dec 13, 2020 at 11:34 PM Tom Jones <[e-mail]>
wrote:

> 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 <[e-mail]>
> 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 <[e-mail]>
>> 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 <[e-mail]>
>>> *Date: *Sunday, December 13, 2020 at 13:20
>>> *To: *Yaron Sheffer <[e-mail]>
>>> *Cc: *Denis <[e-mail]>, GNAP Mailing List <[e-mail]>
>>> *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 <[e-mail]>
>>> 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 <[e-mail]>
>>> 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 <[e-mail]> on behalf of Fabien Imbault <
>>> [e-mail]>
>>> *Date: *Friday, December 11, 2020 at 14:31
>>> *To: *Denis <[e-mail]>
>>> *Cc: *GNAP Mailing List <[e-mail]>
>>> *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 <[e-mail]> 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
>>> [e-mail]
>>> https://www.ietf.org/mailman/listinfo/txauth
>>>
>>> -- TXAuth mailing list [e-mail]
>>> https://www.ietf.org/mailman/listinfo/txauth
>>>
>>> --
>> TXAuth mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/txauth
>>
>