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

Fabien Imbault <> Wed, 22 July 2020 08:26 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id B24253A0FDE for <>; Wed, 22 Jul 2020 01:26:01 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -2.097
X-Spam-Status: No, score=-2.097 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_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 ywMRFR96HUwn for <>; Wed, 22 Jul 2020 01:25:59 -0700 (PDT)
Received: from ( [IPv6:2607:f8b0:4864:20::12e]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by (Postfix) with ESMTPS id 3EE6E3A0FDB for <>; Wed, 22 Jul 2020 01:25:59 -0700 (PDT)
Received: by with SMTP id t18so586645ilh.2 for <>; Wed, 22 Jul 2020 01:25:59 -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=NY2zhKSQN6hFcixx+0mKpQrO6ZGjrrmO2Us/7Q6rvVY=; b=pYKLYypDEVY6BNB6XZgMM+7WN5O+i96zqmRGeM+JLdSmXZOP962psCJXuuFAbIEnkD xFqPW1ffNCn6D1DRg7i/9rgG115sP0xPmAIr9xNGjdy0n5Uuj0iYc5wE4AdtXPh0C2zc 7YMQAiPc9eMiJjVvNxjYeDO9Uf5+tYZVKF+PCTtppWyuhdt4NyrsnjLE8x6uYIoOVpgC i67km0AAg+whjtqfwewfSQSDPh7KMjm+TXf2z3bupp9aQzS564gnfjx0qE8U6nzN2T/Y 4Ww2C5D8sjApNP78G5c4eZwbNX6moVv+sz4M+0j5WpNiyLxAEpmFAWxcWm4j6ENioR/6 +aUg==
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=NY2zhKSQN6hFcixx+0mKpQrO6ZGjrrmO2Us/7Q6rvVY=; b=HVzunGpJOLzy+zsRSwOnWYsA7cxOQ4NnP2wIbMEYGJJ06XNnDR6P08jXt8UQuahGf+ g68tsY8kK9BmFqhqLbY4rc5llmB6Ps4CujQEdZ/sAZaCwFYe37HSc8RfCDY2I7cooScd 7MuHg6DOFe5b7bwTc19g/mIyXCrSFeFxrLAd999cHFNtNbdQYP40HYYhLItY+P5pcPht WUbygrBMbJr3BMFpeFrdL0zARF4iWc2oG56iNMwmkPvrSE7WcH0U3/Zb/RG6aNcru+82 EPeIniKscRoQRvlII2NhP/VoJRo2bCAK2vh6fXNqxyo7wK5VhT04svbrts7418AIfJcZ 0EXg==
X-Gm-Message-State: AOAM530WQG3t6OMkC4FFv7QepumNJr5k4hDiE7nNHRRMMfi5VqR2jYKg Cv/B89GK+Bc/o6yP1vIrdnlu3tt/Lw/zY8bze5nkNj+jeAQ=
X-Google-Smtp-Source: ABdhPJzyyHZ99OwcOPB+6BPDgoG/W3vljPVzOCsTjP62L6iyyJd9Pxyfb7Vbo+vcppgAxj5Zn4XToZ79ymhOnh6cZBw=
X-Received: by 2002:a05:6e02:1313:: with SMTP id g19mr29799514ilr.123.1595406358462; Wed, 22 Jul 2020 01:25:58 -0700 (PDT)
MIME-Version: 1.0
References: <> <> <> <> <> <> <> <>
In-Reply-To: <>
From: Fabien Imbault <>
Date: Wed, 22 Jul 2020 10:25:46 +0200
Message-ID: <>
To: Francis Pouatcha <>
Cc:, Tom Jones <>, Denis <>, Justin Richer <>, Dick Hardt <>
Content-Type: multipart/alternative; boundary="00000000000044c5d105ab037df3"
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: Wed, 22 Jul 2020 08:26:02 -0000

Hi all,

Thanks for that work.
It would make things easier if we could group the definitions which can be
generic (without any knowledge of the GNAP architecture) from the terms
which are dependent on the protocol flow itself.

For terminology, the way it is done in ISO standards is quite interesting
and we probably could reuse some ideas. The general rule of thumb is to
reuse definitions when that's possible and re-define only when necessary.
See for instance
You'll find :
- a definition
- potentially some notes (here we can explain how it differs from an
already existing term used in a different context) and some examples
- related reference (in many cases, we don't even need to reinvent
something, as we just need to be consistent with terms already used in the

Generic definitions :
- resource, claim, consent, grant, authorization -> seems to me these are
generic. Why does it matter in the definition that we know which party is
doing it?
- in most cases, those definitions shouldn't be different from other WGs,
or else we should explain why that is.
- party : if we refer to roles, we need to define that too.
- grant : I don't get what you mean by "material form of an RO consent".
What is material?

Specific definitions :
- User, User-Agent, Client, RO, GS : all these are specific to the way the
protocol is specified, so it does make sense to relate to the parties doing
- But even then, we need to check whether that specificity is required. I'm
not sure I agree with your definition of User, though. In 99% of use cases,
a user is just... a user, i.e. a natural person. Why do we need to make
this definition so convoluted? The User-Agent definition seems enough to
convey the idea that interactions can be done through real users or things.



On Wed, Jul 22, 2020 at 2:33 AM Francis Pouatcha <fpo=> 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.
> 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.
> 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.
> User - the party using the infrastructure of the Client to gain access to
> a Resource or a Claim.
> 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".
> Feedbacks are welcome.
> 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
> --
> Txauth mailing list