Re: [Txauth] Polymorphism (Was: JSON Schema?)

[Justin Richer <[e-mail]>]

An important data-point: RAR is a back-port of the functionality in XYZ to OAuth 2, and Torsten and I intended from the outset that the internal structure be kept in synch. In an ideal world, GNAP’s request data structure would be finished already and RAR would refer to it.

So I am actually proposing:

C) GNAP create a GNAP-specific schema for requesting resources (that allows expression in objects and strings), and that this be developed in concert with RAR in OAuth2 so that data structures that fit into a RAR query will also fit into a GNAP query.

The GNAP query should be a proper superset of OAuth scope and OAuth RAR.

Similarly how an OAuth “scope” string should fit into a GNAP query, an OAuth “RAR” object should fit into a GNAP query. But that doesn’t mean that a GNAP query has to live with all of the limitations and contexts of those. For example, the string values in a GNAP query should be allowed to include spaces. OAuth scopes can’t have spaces because of an unfortunate limitation caused by the encoding in a query parameter, and they also can’t have non-ASCII characters without being encoded. We shouldn’t inherit those limitations here, and any JSON String should be allowed. Similarly, RAR objects need to make sense in the context of the OAuth “resource” parameter, but that constraints doesn’t apply to GNAP.

And yes, if a new query language is developed, I am saying it should be in a top-level parameter, as we should not be placing limitations on what that query language can affect. The GNAP language for requesting things in the access token should be scoped (pun intended) exactly to the access token(s) that it creates. A new query language could affect non-access-token responses as well, and that should be allowed. Combining these is obviously going to be tricky, but that happens any time you cross query languages. Putting them all into a lower-level bucket doesn’t make that go away.

 — Justin

> On Jul 10, 2020, at 4:53 PM, Dick Hardt <[e-mail]> wrote:
> 
> Now that you are saying that the scope string is short hand for the object, the polymorphism makes sense. There is only one type in the array, and a string is shorthand for it. In this thread, you have talked about them being separate things.
> 
> I just reread XYZ-08 section on resources, and there is no mention of polymorphism, or an example of it. Given your comments that XAuth should support both scopes and RAR, and that your proposed schema was based on RAR, that scopes and RAR objects were different things.
> 
> Now it is clear that you are proposing that GNAP have a brand new schema for authorization queries. And on closer inspection of your examples in XYZ, there is no "type" in the property in the object.
> 
> So now I see the choice being: 
> 
> A) reinvent a new, GNAP specific schema for requesting access to resources (XYZ)
> B) reuse the RAR and OAuth scope schemas (XAuth)
> 
> If and when another resource requesting schemas is developed, you propose that it be a new, top level object. I'm proposing it be a new type in the authorizations container.
> 
> Have I captured this accurately?
> 
> /Dick
> 
> 
> 
> 
> 
> On Fri, Jul 10, 2020 at 1:09 PM Justin Richer <[e-mail] <mailto:[e-mail]>> wrote:
> 
> 
>> On Jul 10, 2020, at 1:39 PM, Dick Hardt <[e-mail] <mailto:[e-mail]>> wrote:
>> 
>> 
>> 
>> On Thu, Jul 9, 2020 at 5:46 PM Justin Richer <[e-mail] <mailto:[e-mail]>> wrote:
>> 
>> 
>>> On Jul 9, 2020, at 6:50 PM, Dick Hardt <[e-mail] <mailto:[e-mail]>> wrote:
>>> 
>>> 
>>> 
>>> On Thu, Jul 9, 2020 at 12:17 PM Justin Richer <[e-mail] <mailto:[e-mail]>> wrote:
>>> On Jul 9, 2020, at 2:32 PM, Dick Hardt <[e-mail] <mailto:[e-mail]>> wrote:
>>>> 
>>>> Looks like you missed the point of my code example, as your response is focussed on the aspects I had in comments, so let me clarify. 
>>> 
>>> The point seemed to be about the overall complexity and readability, and that’s what I responded to.
>>> 
>>> It was about the complexity and readability -- of those specific lines of code.
>> 
>> But it’s not just about those lines, it’s about the context that those lines are in and the follow-on code paths that they cause. A lot of what you had “in comments” for the XAuth example would have repeated what was already included in the XYZ example, as I pointed out.
>> 
>> The context between those lines is pretty much the same. Yes, the XAuth example would have had to loop over each scope and RAR object, which is not that different than XYZ looping over each item, and the deciding how to process each item. My point is that checking the object type to decide what to do is an opaque decision vs checking an explicit type.
> 
> The context is really not the same though, as you actually  point out here, and calling one style of type checking “opaque” vs. “explicit” is stylistic and not a helpful comparison. I’m not surprised to find that you think the way you did it is easier, especially given the disconnect we have of what the components of the array represent. I started with some of the type-field-based structures in early versions of XYZ and moved away from them after having bad experiences with building it. There are still a few parts of the XYZ protocol that have that style (the “user” section, for example) that I think need to be changed. I think that the data-type based style of polymorphism, coupled with using the left-hand-side value of object members to indicate type or identifier, is significantly simpler in design and implementation.
> 
> Instead, I realized that we could get a cleaner protocol and better underlying code by dispatching based on the type within the protocol itself. I’ve gotten comments from a number of implementers that they like this design aspect, and I really like it myself.
> 
>>  
>> 
>>> 
>>> I've used JS type polymorphism to provide a cleaner API. For example, making an HTTP request. If I'm good with all the defaults, I can just provide the URI as a string, if I want to change a default, I provide an object and the URI is now a property of the object. Polymorphism allows the caller to have a simpler interface when it is a simple operation.
>>> 
>>> Do you have any examples of JSON polymorphism used in other protocols besides in a JWT?
>> 
>> Sounds to me like you’re describing exactly the kind of polymorphism that I’m talking about here. Use a string where it makes sense and an object where it makes sense, and there’s no ambiguity in calling the function. As you say, it's all about providing a cleaner API for the caller, and making things consistent in the model that the caller and provider are using. It takes a little bit of extra effort on the part of the API provider, but that’s where the complexity cost should be paid.
>> 
>> My examples are not the same at all. The caller has a simpler version of passing the same object. XYZ is passing two different types, where a string means one thing, and an object means something else. The string is not a shorthand for the object.
> 
> The string is, semantically, a shorthand for the object. That’s what I’ve been saying from the beginning, and I’ve put into several examples so far. There are two ways to add rights to an access token resulting from the request. So:
> 
> {
>   “resources”: [ “photo” ]
> }
> 
> Can really be thought of as a shorthand, for example it could expand to this:
> 
> {
>   “resources”: [
>    {
>      “datatypes”: [ “pohoto” ],
>      “actions”: [ “read” ],
>      “locations”: [ “https://server/photoapi/ <https://server/photoapi/>“ ]
>    }
> }
> 
> In this straw man, if the client wants write access to the API, it needs to use the object-style request to do so.
> 
> It’s up to the AS, or really the API that it’s protecting, to figure out what that expansion really looks like, and how much of the more complex policy to expose. My example of processing only string-based resource requests was for the case where the AS only gives the shorthand version, and doesn’t allow detailed access into its protection policies. It’s not a different kind of request, it’s a shorthand, much like passing an identifier in lieu of a key to identify the client software instance making the call.
> 
> But really, the point is that in both cases the string and the object both represent the same kind of thing: a piece of access rights that the client is requesting at the AS which gets put into the access token. Thus, having them together in a single array and processing them together makes sense to me. If you are thinking of strings and objects as completely different from each other,  you’d expect them to be handled separately, but I don’t think they are actually different because they both represent a view of the same underlying thing.
> 
> 
>> 
>> In polymorphic APIs, it makes the code cleaner to pass a singular item when the API takes an array, or the API takes a string for the common property of the object which is the parameter.
> 
> Yes, those are two examples of why it can be good. There are other reasons to apply it, like having an array with differently typed items that represent the same kind of thing underneath.
> 
>> Here are some code examples for both:
>> 
>> // passing a singular item, a simpler version of foo(['string'])
>> foo('string')
>> // passing a plurality of the same item
>> foo(['string1','string2','string3'])
>> 
>> // implementation
>> foo = ( param ) => {
>>     var a = []
>>     if (typeof param === 'string') {
>>         a[0] = param;
>>     } else if (typeof param === 'array') {
>>         a = param;
>>     }
>>     // process array a
>> }
>> 
>> 
>> // pass a uri as string and accept all defaults, a simpler version of bar({uri:'uri'})
>> bar('uri')
>> // pass an object with uri and method
>> bar({uri: 'uri', method: 'POST'})
>> 
>> // implementation
>> bar = ( param ) => {
>>     var p = DEFAULT_OBJ;
>>     if (typeof param === 'string') {
>>         p.uri = param;
>>     } else if (typeof param === 'object') {
>>         Object.keys(param).forEach( item => {
>>             p[item] = param[item];
>>         });
>>     }
>>     // process p object
>> }
>> 
>> In GNAP, we could take a string rather than an array for a scope parameter, for example:
>> 
>> "scope": "read"
>> 
>> instead of 
>> 
>> "scope": ["read"]
>> 
>> OIDC uses the latter polymorphism for 
>> 
>> { 
>>   "name": {"essential": true},
>>   "photo": null
>> }
>> 
>> as being shorthand for 
>> 
>> { 
>>   "name": {"essential": true},
>>   "photo": {"essential": false}
>> }
>> 
> 
> All of these are great examples of why object-type-based polymorphism is a good and powerful thing, and that’s the approach I’m saying we should use within the GNAP protocol. I would argue that the last one isn’t polymorphism so much as a default based on a null value (often taken as a special class of an “object” value anyway), but that’s splitting hairs.
> 
>>  
>> 
>>>  
>>> 
>>>> 
>>>> This line (which is determining the type of the item in the array):
>>>> 
>>>> if (typeof item === string')
>>>> 
>>>> is implicitly stating that the item is an oauth scope. 
>>> 
>>> No, it is not. It is saying that it is a resource request represented as a string. One way to represent a resource request as a string is an OAuth 2 style scope. And if you’re building up from an existing OAuth 2 system, then you could use a scope there. But that’s not the same as stating “the item is a scope”. In my examples, I had been trying to use the terminology that you were using, but I’m afraid that made things more unclear.
>>> 
>>> We are comparing how to do it in XYZ vs XAuth -- so to make it apples and apples, the string is a scope, since that is the use case we are looking at.
>> 
>> You can use a scope as the string, and if you want to think of all string values in this request as all being “scopes", that’s fine, but only if you can concede that the scope can mean whatever the AS wants. I think that perhaps you’re putting a certain amount of semantic weight to “scope” that I’m missing, though.
>> 
>> The string could be a scope, or it could be a claim such as in my "oidc" type example. The AS could support both scope and claims, and they could have overlapping string values. 
> 
> Both would represent “things that the client wants back in the access token”, and therefore the AS would need to differentiate. In that case I think it actually makes a lot more sense for the AS to define a more rich mechanism to request user information. In XYZ it could look like this:
> 
> {
>    “resources”: [
>      {
>         “type”: “oidc_userinfo”,
>         “datatypes”: [ “email”, “phone”, “address”, “profile.photo" ]
>      }
>    ]
> }
> 
> But defining the details of that kind of query is clearly outside the scope of GNAP (see below), and I think better suited to an identity protocol built on top of GNAP.
> 
>> 
>>  
>> 
>>>  
>>> 
>>>> Whereas it is explicit in this statement
>>>> 
>>>> if (authorizations.type === 'oauth_scope')
>>>> 
>>>> which I think it easier to understand what is happening (in my opinion of course).
>>>> 
>>>> XYZ has types, they are just implicit. RAR has explicit types, and that does not look to be holding back RAR. I don't understand why you think having explicit types will hold us back. 
>>> 
>>> The “type” in RAR is a name spacing device to allow extensibility in different aspects of the request. This is at a lower layer than how they’re being applied here, and it therefore makes more sense at that layer. It’s a way for a particular API to define the dimensions that it cares about in its request. It’s not really an even comparison.
>>> 
>>> And the type in XAuth authorizations is different schemas for making a request. "oauth_scope", "oauth_rar", and now "oidc". I would expect that there may be more in the future, and we have a clear way of adding schemas, and for the client and AS to know they are talking the same "language".
>> 
>> And I’m saying that additional “schemas” for requesting information should be defined separately from the GNAP schema. We disagree on this topic and we’re repeating ourselves. 
>> 
>> The charter is pretty clear that GNAP should not define schemas, so I don't know what you mean by the "the GNAP schema"
>>  
> 
> That’s not true. The charter is clear that "nor is the group chartered to develop schemas for user information, profiles, or other identity attributes”, but not that it’s not defining schemas for the other parts of the protocol. I’ve been clear on the other thread that we shouldn’t be defining a user schema, for attachment either to the access token or non-identifier items returned directly as plaintext or in assertions. 
> 
> By my read, we are fully within our charter to define schemas for authorization requests and responses, including both coarse and fine-grained access. I understand that it’s your stance that we should simply re-use OAuth 2’s “scope” parameter for this, and I disagree with that. My proposed approach is to have a place within the GNAP protocol to plug in a “scope” value if you have one, and for the AS to interpret it, but not to have that value always be a “scope”. 
> 
>> 
>>>  
>>> 
>>>> Do you want to let the string and object be anything the AS and RS decide they could mean? 
>>> 
>>> Yes. Just like the AS can decide that an OAuth scope could mean any number of things.
>>> 
>>> That was what I was afraid of. While an OAuth scope could mean whatever the AS decides it wants to be, the Client and AS know it is an OAuth scope.
>> 
>> How is that any different? I’m confused as to why you think it’s important to call this item a “scope” so that you “know what it is”, but then you’re OK with “scope” meaning literally anything.
>> 
>> A scope string is one of a set of strings defined by the AS.
>> 
>> The AS may use strings to define a different schema, such as which claims to return from a userinfo endpoint.
>> 
> 
> Exactly. A scope is a string that represents access to something controlled by the AS. The object also represents that same thing, but in multiple, more specific dimensions. 
> 
>>  I'm going to separate the my other responses into separate threads as they are different topics.
>> 
>> /Dick
>> 
>> ᐧ
> 
> 
>  - Justin