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

Dick Hardt <> Thu, 23 July 2020 23:52 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 9D4923A0A0E for <>; Thu, 23 Jul 2020 16:52:58 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -2.096
X-Spam-Status: No, score=-2.096 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, HTML_FONT_LOW_CONTRAST=0.001, HTML_MESSAGE=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: (amavisd-new); dkim=pass (2048-bit key)
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id bi13qUSdfVFZ for <>; Thu, 23 Jul 2020 16:52:55 -0700 (PDT)
Received: from ( [IPv6:2a00:1450:4864:20::130]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by (Postfix) with ESMTPS id AF9BF3A09C3 for <>; Thu, 23 Jul 2020 16:52:54 -0700 (PDT)
Received: by with SMTP id j21so4234900lfe.6 for <>; Thu, 23 Jul 2020 16:52:54 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=an9XLTax23n+WyeRIbSTk0DQ7vxQ+glPkcq/6MdwGNI=; b=bvX5w0BlSSEOSun/TCQTaSLW0Ayq/M0sFwJLl8np9Ot2bjxtjinqdsZbx2XHRULZ26 81iKC1ELPyDmarAQ7dNhOseW/vpfUdPgOFeRm1/2GT7MJ+Ux5RjPMkXf/QYxqIaeKhca HG6SmTDNI1Op0cFPK13dIGpdSoMfZnOU0SZc9GU/7WiWI8s3if+kGsMHoz6kChPYq6E9 uqDGvMlGJ9qiFVuWn4IkkgcvZei2U8nY3VkoG79md2tpLFSSwXX4tCZIoBL0ol8F0kiB dgMKD75IrQQqckIVYGDhSQe+QAoBDgwKTYGuNWWbNtUQzvewo3E+mnnApCW8I34Rwkgs bXUg==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=an9XLTax23n+WyeRIbSTk0DQ7vxQ+glPkcq/6MdwGNI=; b=XR6dW6VdeqDyU84vnWQPIiNpQMU+vL6dTux8LWP4qn8+eOmTwcFQIyYNtQvusWM4dB QJC4TNMmAhW4DYh8ZEPC45Z1hC1v0rr02Mgs0VxUEReXJYGwMOeR8F+Df+DAtJxH6h+d 3G5cmelF5ttQRUHnFM79f/aHtDFg1Jm4sn6tCvP58kV+05xuqH9zcMO8nxRdAyGQNwfF +RbbrzGn4myKreh+Uh50hVWS/TDVWqYNG5ySialaGS0ynSs/0nHx1gLBsbhz+E1RWiIw jzH7fD0tVXwVJ/UepX8XzBQFodkCl5hCGygMDC7VtvwwwmMiAMIH0tDoqe5mKkmlg+II 7A5A==
X-Gm-Message-State: AOAM532es4QTKp6pHURvqzuI3xbztlGh4QZ3d4nP8MDH1qoLx235n5CE pKbpLddpyehm5TITUhrU/Ey+2hbbooQ0oZRRLGQ=
X-Google-Smtp-Source: ABdhPJyb/+3tiQZrJAIpyNYS0dhAHGy1L3xBUW8jo2SrVttDG96DtVGO22H74behnLY4iaxnXwfvyOv2Bdt9zSV6zCw=
X-Received: by 2002:ac2:4a9d:: with SMTP id l29mr3446650lfp.23.1595548372332; Thu, 23 Jul 2020 16:52:52 -0700 (PDT)
MIME-Version: 1.0
References: <> <> <> <> <> <> <> <> <>
In-Reply-To: <>
From: Dick Hardt <>
Date: Thu, 23 Jul 2020 16:52:15 -0700
Message-ID: <>
To: Justin Richer <>
Cc: Francis Pouatcha <>,, Tom Jones <>, Denis <>
Content-Type: multipart/alternative; boundary="000000000000f474ea05ab248db6"
Archived-At: <>
Subject: Re: [Txauth] Reviewing draft-hardt-xauth-protocol-11 - Dictionary
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Thu, 23 Jul 2020 23:53:00 -0000

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
      - 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.



On Thu, Jul 23, 2020 at 8:07 AM Justin Richer <> 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 <> 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 <> wrote:
>> On Tue, Jul 21, 2020 at 2:15 PM Dick Hardt <> wrote:
>>> On Tue, Jul 21, 2020 at 11:09 AM Francis Pouatcha <>
>>> wrote:
>>>> On Tue, Jul 21, 2020 at 1:59 PM Dick Hardt <>
>>>> 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
> --
> Francis Pouatcha
> Co-Founder and Technical Lead
> adorsys GmbH & Co. KG