Re: [Txauth] Reviewing draft-hardt-xauth-protocol-11 - Dictionary

[Francis Pouatcha <[e-mail]>]

Hello Justin,

thanks a lot for the feedback, some comments inline,

On Thu, Jul 23, 2020 at 11:07 AM Justin Richer <[e-mail]> wrote:

> Up-front question to the Chairs, do we have a good place to capture this
> kind of thing? A non-spec document like this would be a good candidate for
> a wiki page. Do we have plans to set up a GitHub repository or similar? If
> so we could use the wiki capabilities there to at least get this stuff
> written down. Use cases would be good to capture there as well.
>
>
>
> Francis,
>
> First, I want to thank you for putting the work in to getting some
> vocabulary down. This is not an easy task! Some notes on specific items
> inline below.
>
> On Jul 21, 2020, at 8:33 PM, Francis Pouatcha <[e-mail]> wrote:
>
> Hello Dick, Justin, Tom, Denis,
>
> Below is a new version of the dictionary includings comments from
> different threads. Change log includes:
> - avoided the expression "owns a resource" in favor of the expression
> "controls a resource"
> - included the clarification "resource access" and "claim release"
> - included a clarification User vs. RO
> - tried to clarify the word User-Agent
> - added the definition of a Claim
>
> Terms
> =====
>
> Party - represents a role in the GNAP protocol flow. A party can take the
> form of a web service, an application installed on the user device and
> acting autonomously or the form of a natural person (resp. of an autonomous
> device) using an application to interact with other parties.
>
> Resource - a piece of data or web service
>       - controlled by a Resource Owner (RO),
>       - held and guarded by a Resource Server (RS) and
>       - serviced by the RS to a Client, if the Client provides a valid
> Authorization.
>
> Claim - a piece of data
>       - controlled by a Resource Owner (RO),
>       - held and guarded by the Grant Server (GS) and
>       - released by the GS to a Client as part of an Authorization.
>
>
> The differentiation between “resource” and “claim” is important since it
> separates items that get tied to an access token’s rights (“resources”)
> with items that come back directly to the client without going through a
> separate API. The term “claim” is problematic here though because it is
> used broadly in the community to mean, roughly, “a statement about the end
> user”. It’s therefore both too broad and too narrow in the wrong ways: a
> “claim” could come back as part of an API response, like the OIDC UserInfo
> Endpoint, and so it’s not a good name for this item. Even the OIDC “claims”
> query language defines several different targets for returning the “claims”
> about the user, and none of them match the method that GNAP is looking to
> use here. A “claim” is also generally understood in the identity community
> to be a statement about the user, and the data coming back directly to the
> client might be about the user or something else, especially as we look
> forward to extensions of GNAP.
>
I fully understand your problem. It won't be obvious to find a replacement.
I often think about the word Assertion. But I not sure if the word won't
come with its own controversies.

Essential for us now is to narrow the intended meaning of the term in the
context of GNAP and then look for the correct replacement, if any.  What
about this?

<In the context of GNAP>
A Claim
  - is an "assertion" of the truth of some properties or attributes of the
RO.
  Note-1: A Claim is produced either by the GS or by another claim source.
  Note-2: A Claim is held and guarded by the Grant Server (GS).
  Note-3: A Claim is released by the GS to a Client.
                  [REMOVED: "as part of an Authorization", as Justin
mentions bellow possibility of a claim to be included in userInfo and other
introspection responses]
  Note-4: The release of a Claim is controlled by the RO
                  [ADDED: "release", to distinguish it from the
"production" of the claim. Some Claims are just provided by the RO, some
other Claims are produced by authorities, that take care of verifying the
claim and/or legitimating them]


> I think we should focus on the separation of the delivery mechanism, but
> I’m not sure what good alternatives would be. Perhaps:
>
>  - “access right” for things tied to the API/token
>  - “data response” for things coming back directly to the client
>
Here you are referring to the target of the information. And it is more
difficult to nail formalized. A claim might be targeted for the RS and not
the Client.

I suggest we first stay with: "resource access" and "claim release" (both
Grants as mentioned by Dick above). Rationale being:
- the clarification that a Resource is not a Claim, but that both are
controlled by the RO
- the clarification of a Claim is held by the GS,
- the clarification of a Resource is held by the RS,

>
> I’m not particularly thrilled by these names, but I think recent list
> conversation shows that we need to get away from “claim” as it’s overloaded.
>
Let us look at this after we have narrowed a definition in the context of
GNAP.


>
> Resource Owner (RO) - the party that
>       - controls a Resource,
>       - relies on the services the GS to manage access to that Resource,
>       - relies on the services of a RS to hold the Resource and guard
> access to that Resource,
>       - controls a Claim,
>       - relies on the services the GS to release that Claim to a Client.
>
> Resource Server (RS) - the party that
>       - holds a resource and guards access to that resource on behalf of
> the RO,
>       - services the Resource to the requesting Client, provided the
> Client presents a valid Authorization.
>       The RS is generally deployed as a web service.
>
> Grant Server (GS) - the party that
>       - manages access to a Resource on behalf of the RO,
>       - holds Claims and releases them when consented by the RO.
>       For each Resource access request, the GS might request the Consent
> of the RO and produce a corresponding Authorization that is given to the
> requesting Client.
>
>
> I don’t like the shift from “Authorization Server” to “Grant Server”, and
> it especially doesn’t make sense in light of the definitions of “grant” and
> “authorization” above. I believe we should stick with “Authorization
> Server” if it’s a single role. I would also propose that we have a separate
> term for the RO-interactive portion vs. the client-facing portion, as has
> been brought up in a few threads. Maybe these get different names entirely,
> or maybe they are “aspects” of the AS, I’m not sure.
>
I also did not see any difference to functions of an AS. But i suggest we
shift the discussion on renaming the term GS to another thread and keep the
focus on this thread on elaborating terms in the context of GNAP.


>
> Consent - act of an RO :
>       - approving access to a Resource, means approval that a Resource he
> controls can be given to the Client by the RS.
>       - approving release of a Claim, means approval that a Claim he
> controls can be included by the GS in an Authorization to be returned to
> the Client.
>
> Grant - material form of an RO Consent. In order not to interact with the
> RO on each Resource access request, the GS might store the RO Consent in
> the form of a Grant for reuse.
>
> Authorization - externalized form of a Grant as known to the GS and the RS.
>       - The GS converts a Grant into an Authorization for use in a
> Resource access request.
>       - The RS evaluates an Authorization to decide on whether or not to
> release the Resource to the Client.
>
> Client - the party that provides the infrastructure used by a User to
> access a Resource. The client infrastructure is designed to:
>       - Receive the resource access request from the User,
>       - Interact with the RS to discover authorization requirements,
>       - Interact with the GS to obtain an Authorization to access the
> Resource,
>       - Interact with the RS to access the Resource on behalf of the User.
>
>
> I think we should be clear that what we call the “client” is a piece of
> software operated by the user. It’s true that this software might have
> multiple parts of its “infrastructure” but it’s always software.
>
Yes.
Client - the party that implements the infrastructure used by a User to
access a Resource:
   Note-1: a Client is always a piece of software running either on the
User device or as a web service.
   Note-2: The Client infrastructure is designed to:
      - receive the resource access request from the User,
      - interact with the RS to discover authorization requirements,
      - interact with the GS to obtain an Authorization to access the
Resource,
      - interact with the RS to access the Resource on behalf of the User.


>
> User - the party using the infrastructure of the Client to gain access to
> a Resource or a Claim.
>
>
> In UMA, we call this the “Requesting Party”, or RqP. We might want to
> consider adopting this terminology here as well.
>
I admit the term User is confusing. Like for GS vs AS above, let us start a
new thread on this.


>
> Clarifications:
> ==========
>
> User vs. RO :
>       - the User is the party using the infrastructure of the Client to
> gain access to a Resource or a Claim,
>       - the RO is the party controlling access to a Resource or
> controlling the release of a Claim.
> In many use cases, User and RO will be represented by the same party (see
> oAuth2), but GNAP exposes use cases where User and RO are represented by
> different parties.
>
> User-Agent :
> User and RO are parties that might be represented by a natural person or
> an autonomous device. In those cases, User (resp. RO) might need the help
> of an application to interact with other parties. Such an application is
> generally referred to as the "User-Agent".
>
>
> The term “user agent” is often used to be equivalent to the web browser,
> and not the more general use here. I think we’re seeing more “agent”
> terminology for helper applications like digital wallets and AI bots, which
> would seem to be covered under your definition here.
>
>
> Feedbacks are welcome.
>
> Yes. We do need feedback here.

Just as a summary:
- I will update the dictionary after we receive feedback on the definitions
of Claim and Client as reformulated in the answer.
- would you start a new thread for the renaming of GS to AS?
- would you start a new thread for the renaming of Client to Requesting
Party.

Thanks a lot for the feedback.

-- 
Francis Pouatcha
Co-Founder and Technical Lead
adorsys GmbH & Co. KG
https://adorsys-platform.de/solutions/