Re: [GNAP] Terminology proposal

[Fabien Imbault <[e-mail]>]

Ok but if we limit to protected resources, we don't have that problem, so
typically is not needed.

On Sun, Dec 13, 2020 at 8:26 PM Yaron Sheffer <[e-mail]> wrote:

> Hi Fabien,
>
>
>
> “Typically” means “usually, though there may be fully public resources
> where some operations don’t require any authorization, but I don’t want a
> normative statement in the Terminology section…”
>
>
>
> Thanks,
>
>                 Yaron
>
>
>
> *From: *Fabien Imbault <[e-mail]>
> *Date: *Sunday, December 13, 2020 at 21:21
> *To: *Yaron Sheffer <[e-mail]>
> *Cc: *Denis <[e-mail]>, GNAP Mailing List <[e-mail]>
> *Subject: *Re: [GNAP] Terminology proposal
>
>
>
> 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
>
>