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

[Dick Hardt <[e-mail]>]

Hi Francis

Thanks again for putting this together. I have taken your definitions and
adjusted them to match how I think of them. I dropped the term "parties"
because I did not think it added value. I am explicit about what each party
is -- software, a human, or an entity. Let me know where you disagree!


Resource - protected data or software functionality
      - controlled by a Resource Owner (RO),
      - protected by the Resource Server (RS)

Claim - a statement about the User
      - may be obtained from the Grant Server (GS) by a Client
      - may be a Resource the Client can access through an RS

Grant - the Claims and/or Resource Access the User and/or RO have granted
to the Client by the GS
    - requested by a Client
    - granted by a GS after any required consent has been obtained from the
User and/or RO

Access Token - an artifact representing the access a client has been
granted to one or more Resources
    - created by the GS
    - presented by the Client when accessing a Resource at an RS

Resource Owner (RO) - the entity that
      - controls a Resource,
      - has delegated Resource access control to one or more GSes
      - may be the User

Resource Server (RS) - the software that controls access to one or more
Resources
      - accessed via an API by Clients presenting an access token
      - accepts access tokens from one or more GSes

Grant Server (GS) - the software that manages Grants
    - has been delegated to manage Resource access by the RO
    - has been delegated to release Claims about the User
    - grants the Client access to Resources after obtaining the required
consent from the RO
    - provides the Client Claims about the User after obtaining the
required consent from the User

Client - the software that wants to access Resources and obtain Claims
    - executed by a User or a non-human service account
    - requests Grants from the Grant Server
    - accesses Resources at an RS using access tokens

User - the human using a Client
    - may also be the RO for one or more Resources
    - may have Claims managed at a GS

Some comments:

A Claim is a well understood term in the field. We should use it. It is
still a Claim if it comes directly from the GS or from an RS.

I think Grant Server is the right term. A Grant contains claims and/or
access to resources. I have defined all the terms above without using the
term authorization. :) -- I am pondering renaming most things called
Authorization in XAuth to Access.

Claim Issuer - I think we may need to add this party to our nomenclature.
This is the entity that issues Claims. It may be a GS or an RS.

/Dick

ᐧ

On Thu, Jul 23, 2020 at 8: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 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
>
> 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.
>
>
> 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.
>
>
> 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.
>
>
> 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.
>
>
> 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.
>
>
> Again, thanks so much for getting this going!
>
>  — Justin
>
> Best regards,
> /Francis
>
>
> On Tue, Jul 21, 2020 at 2:27 PM Francis Pouatcha <[e-mail]> wrote:
>
>>
>>
>> On Tue, Jul 21, 2020 at 2:15 PM Dick Hardt <[e-mail]> wrote:
>>
>>>
>>>
>>> On Tue, Jul 21, 2020 at 11:09 AM Francis Pouatcha <[e-mail]>
>>> wrote:
>>>
>>>>
>>>> On Tue, Jul 21, 2020 at 1:59 PM Dick Hardt <[e-mail]>
>>>> wrote:
>>>>
>>>>> FYI: I consider the release of claims to be an "authorization" as
>>>>> well.
>>>>>
>>>> Great. Then it is included.
>>>>
>>>
>>> I pivoted to using the term Grant rather than authorization so that it
>>> included both authorizing access to a resource, and authorizing the release
>>> of an identity claim.
>>>
>>> Perhaps we should not use the word "authorization"?
>>>
>> Authorization is currently used to refer to the token issued by the GSand
>> presented to the RS by the Client. I have no alternative word for now.
>>
>>>
>>> "resource access" and "claim release"
>>>
>>> A Grant then covers both?
>>>
>> Yes, Great! The word Grant fits best for both. I suggest adding this
>> clarification to that dictionary.
>>
>>>
>>>
>>>
>>>>
>>>>> IE, the user authorizes the GS to release a DOB claim to a Client.
>>>>>
>>>> I guess you mean the "RO" authorizes the GS to release a DOB!
>>>>
>>>
>>> Yes, thanks for clarifying!
>>>
>>> /Dick
>>>
>>>>
>>
>> --
>> Francis Pouatcha
>> Co-Founder and Technical Lead
>> adorsys GmbH & Co. KG
>> https://adorsys-platform.de/solutions/
>>
>
>
> --
> Francis Pouatcha
> Co-Founder and Technical Lead
> adorsys GmbH & Co. KG
> https://adorsys-platform.de/solutions/
>
>
>