Re: [GNAP] Comments on the GNAP Wiki Terminology

[Justin Richer <[e-mail]>]

There’s a subtlety about “subject information” that I think we need to be careful not to lose, in that it’s the intersection of two different aspects of data rights being given to the client. I’m not sure how best to frame this, so apologies if this sprawls a bit:

First, there’s the dimension of how the data is transmitted to the client. This is a fundamental difference between rights associated with an access token and data being sent back directly to the client in a response message from the AS. The access token is handled by the “resources” request (pending proposed restructure/rename, but that’s the current spec). This tells the AS the things the token can do, but as we all know a big part of that in practice is about what data the token can be used for, and therefore what data the client has access to. The other information is what’s sent directly to the client, and it’s somewhat “new” for GNAP. OpenID Connect showed us the value of passing back an assertion directly to the client, and GNAP is making this kind of “Direct returned information” a first-class citizen, to the point that mechanisms for returning this is in our charter. This could be wrapped in an assertion or returned as raw data, and GNAP currently allows both.

The second dimension is what the data is about, regardless of how it gets back. There are lots of ways to look at this, but one fundamental question is whether the data is :about: the end user or not. Identity is far from the only use case for GNAP, but we know that it’s going to be a driving one for many developers. And when you’re talking about identity information, the distinction between the RQ and RO really comes into sharp relief: are you asking about the current user, or about some other user on a different system, and are they the same person?

So in total it’s something like this:

                   |     Delivery Method       |
                   |                           |
                   | Direct      |  Resource   |
-----------------------------------------------+
          End User | Subject     |  UserInfo   |
    Data           | Information |  Endpoint   |
 Subject  -------------------------------------+
            Other  | ???         |  Resource   |
                   |             |  Server API |
-----------------------------------------------+

Is this a useful diagram and distinction to make in our discussion?

Also for what it’s worth, the OpenID Connect “claims” language would cover everything in that square. It’s primarily about the end user, but doesn’t have to be as the OIDC spec itself stats that it provides methods for "Claims about the End-User and the Authentication event”. In other words, a “claim” is any statement made by an potentially authoritative source, the AS.

 — Justin

> On Dec 18, 2020, at 12:02 PM, Fabien Imbault <[e-mail]> wrote:
> 
> Thanks Denis, that's a really useful feedback. I'll review that in more detail, but something that's really not clear to me is the last one, subject information.
> 
> 1) is it about the end-user ? or the RO ? (as is the current definition in V02)
> 2) why do we even need to call it subject information ? For instance if it's about the end-user, it should only be end-user information. 
> 3) do we want to use entity or subject in the definitions ? (cf RO for instance). Regarding natural person vs entity we had a discussion on the mailing list previously. 
> 
> Cheers,
> Fabien
> 
> On Fri, Dec 18, 2020 at 5:47 PM Denis <[e-mail] <mailto:[e-mail]>> wrote:
> 
> FYI, the wiki page is there:  https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology <https://github.com/ietf-wg-gnap/gnap-core-protocol/wiki/Terminology>
> FYI first, there is a useful web page where you can find all the ISO definitions as well as the text for any ISO standard (up to its definition section only): 
> https://www.iso.org/obp <https://www.iso.org/obp> 
> This may provide some ideas and you will notice that a given term may be used in different ISO standards with a different definition.  
> 
> I have nine comments (each one being numbered). 
> 
> 1) Current definition of AS:  
> 
> The current definition is: 
> 
>      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 
> This is fine in general (but see later another comment about it), but the word privileges is left undefined.  
> 
> 2) Definition of a privilege 
> A suggested "privilege" definition has been proposed in the wiki page: "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> . 
> In the "other def.", the term is considered to be a synonym of a permission.  
> 
> ISO/IEC 29146:2016(en), 3.8 (very long) definition is the following : 
> 
>      privilege  
>     access right 
>     permission 
>     authorization to a subject (3.15) <https://www.iso.org/obp/ui#:term:3.15> to access a resource (3.14) <https://www.iso.org/obp/ui#:term:3.14> 
> 
>     Note 1 to entry: Privilege is a necessary but not sufficient condition for access. Access occurs when the access request is granted according to its access control policy. 
>                               The access control policy is based on privileges and may include other environmental factors (e.g. time-of-day, location, etc.) 
> 
>     Note 2 to entry: Privileges take the form of data presented by a subject or obtained for a subject that is used by a Policy Decision Point in order to grant or deny an operation 
>                               that a subject is willing to perform on a resource. 
> (...) 
> I propose the following: 
> 
>         privilege: right or attribute associated with an end-user 
> with: 
>         right: ability given to an end-user to perform a given operation on an object under the control of a RS 
> 
>       attribute: characteristics or property related to an end-user 
> 
> 3) Definition of a Client 
> 
> The current definition is: 
>      Client 
>      Definition: application that consumes resources from one or several RSs, possibly requiring a negotiation of access privileges with one or several ASs 
> 
>      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. 
> 
> Previously, I proposed:
>   
>       Client: application used by an end-user to interact with an AS or a RS 
> 
> The current definition is missing to indicate who is operating the client. It is an end-user, i.e. it is not another application, nor a process, nor an entity. 
> The definition should capture this point.
>  
> A second point: the current definition is using the wording "requiring a negotiation". There is no "negotiation". Either the AS has or has not the "access privileges". 
> The words "a negotiation of" should be deleted. 
> 
> This raises the point where this definition of a "Client" is using the wording "access privileges" whereas the definition of an "Authorization Server (AS)" 
> is using the word "privileges". We should make both definitions consistent. I have a slight preference for "access privileges", but I could also live with "privileges".  
> 
> Hence my proposals: 
> 
>      Client 
>      application operated by an end-user that consumes resources from one or several RSs, possibly requiring access privileges from one or several ASs 
> 
>     Authorization Server (AS) 
>      server that grants access privileges to a particular end-user and that provides them to a client in the form of an access token 
>  
> 4) Definition of a Resource Server (RS) 
> 
> The current definition is: 
> 
>      Resource Server (RS) 
>      Definition: server that provides operations on protected resources; such operations require that the client provides valid access tokens issued by an AS 
> A RS may offer both public resources and protected resources. Valid access tokens are only needed for protected resources. 
> I propose the following definition while merging the two sentences: 
> 
>       Resource Server (RS) 
>       server that provides operations on resources where protected operations require that the client provides one or more valid access tokens issued by one or more ASs 
> In the  above modification I added "one or more ". I am presuming that GNAP will allow the presentation of more that one access token from different ASs 
> in order to allow an end-user to perform one operation on a protected resource. 
>  
> 5) Definition of Resource Owner  
> 
> The current definition is: 
>      Resource Owner (RO) 
>      Definition: personal or organizational entity that may grant privileges on resources it has authority upon 
>     Note: the act of granting privileges may be manual (i.e. through an interaction) or automatic (i.e. through predefined rules). 
> 
> I don't know what a "personal entity" is but I know what a "natural person" is. 
> 
> Furthermore, a Resource Owner is not granting privileges (or access privileges) in the same way an AS is doing. 
> 
> It is interesting to take a look at ISO 20078-1:2019(en), 3.1.4 where Resource Owner (RO) is defined as: 
> 
>       responsible party for the Resource(s) 
>       Note 1 to entry: The Resource Owner is responsible for granting, denying, and revoking Access to Resource(s). 
>       Note 2 to entry: The responsible Resource Owner is determined by the concrete Resource. 
> I propose: 
>      Resource Owner (RO) 
>      natural person or organizational entity that may grant or deny operations on resources it has authority upon 
>     Note: the act of granting or denying an operation may be manual (i.e. through an interaction) or automatic (i.e. through predefined rules). 
> 
> 6) Definition of Access Token  
> The current definition is: 
>      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) 
> The definition is fine, but not the two Notes. 
> The second sentence from the Note 1 is stating: "The AS usually provides a method for the RO to revoke the privileges at any point in time". 
> Revoking "the privileges" is different from revoking an "access token". The second sentence of this Note 1 which is supposed to be about access token is confusing. 
> The privileges may be changed at any point in time using a management function. Access tokens can be short-lived and thus don't need to be revoked. 
> Any call-back from a RS to an AS should be avoided in order to respect the user's privacy. 
> 
> Therefore, I propose to remove the second part of this Note 1 and to replace "the" by "a" at the beginning of the first sentence. 
> Note 2 is stating: 
>       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) 
> From the discussion on the list, I believe that we don't consider bearer tokens. Note 2 should be removed. 
> So my proposal is as follows: 
>      Access token 
>      digitally signed data that contains specific rights and/or attributes    
>     Note: an access token can be issued to an end-user (usually requiring his authentication) and subsequently refreshed. 
> 
> 7) Definition of Grant  
> The current definition is: 
>      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 
> 
> The words ", as a privilege given to" are unnecessary" 
> I propose: 
>      Grant
>      (verb): to permit an end-user to exercise some rights and/or to assert some attributes at a specific time and during a specific duration 
>     (noun): the act of granting 
>  
>  
> 8) Definition of Resource  
> The current definition is: 
>      Resource 
>       Definition: protected API served by a RS and accessed by a client, if and only if a valid access token is provided 
> This definition is incorrect. This definition would be fine for a Protected Resource. Change it into "Protected Resource": 
>      Protected Resource 
>      protected API served by a RS and that can be accessed by a client, if and only if a valid access token is provided 
> If a definition of a Resource is needed, I propose: 
>      Resource 
>      public or protected resource from a RS
> 
> 9) Definition of Subject Information 
> 
> The current definition is: 
>  
> Subject Information 
> Definition: claim asserted locally by an AS about a person, organization or device 
> Source: https://tools.ietf.org/html/draft-ietf-secevent-subject-identifiers-06 <https://tools.ietf.org/html/draft-ietf-secevent-subject-identifiers-06> (unless we plan to use something specific to GNAP) 
> 
> This is information returned by an AS about an end-user. 
> I would thus simply propose instead:
> 
>      Subject Information 
>      information returned to a Client by an AS about an end-user 
>   
> Denis
> 
> -- 
> TXAuth mailing list
> [e-mail] <mailto:[e-mail]>
> https://www.ietf.org/mailman/listinfo/txauth <https://www.ietf.org/mailman/listinfo/txauth>
> -- 
> TXAuth mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/txauth