Subject: [OAUTH-WG] Namespacing "type" in RAR

From: Justin Richer <[email-masked]>
Date: Fri, 17 Jul 2020 11:38:52 -0400

The “type” field in the RAR spec serves an important purpose: it defines what goes in the rest of the object, including what other fields are available and what values are allowed for those fields. It provides an API-level definition for requesting access based on multiple dimensions, and that’s really powerful and flexible. Each type can use any of the general-purpose fields like “actions” and/or add its own fields as necessary, and the “type” parameter keeps everything well-defined.

The question, then, is what defines what’s allowed to go into the “type” field itself? And what defines how that value maps to the requirements for the rest of the object? The draft doesn’t say anything about it at the moment, but we should choose the direction we want to go. On the surface, there are three main options:

1) Require all values to be registered. 
2) Require all values to be collision-resistant (eg, URIs).
3) Require all values to be defined by the AS (and/or the RS’s that it protects).

Are there any other options?

Here are my thoughts on each approach:

1) While it usually makes sense to register things for interoperability, this is a case where I think that a registry would actually hurt interoperability and adoption. Like a “scope” value, the RAR “type” is ultimately up to the AS and RS to interpret in their own context. We :want: people to define rich objects for their APIs and enable fine-grained access for their systems, and if they have to register something every time they come up with a new API to protect, it’s going to be an unmaintainable mess. I genuinely don’t think this would scale, and that most developers would just ignore the registry and do what they want anyway. And since many of these systems are inside domains, it’s completely unenforceable in practice.

2) This seems reasonable, but it’s a bit of a nuisance to require everything to be a URI here. It’s long and ugly, and a lot of APIs are going to be internal to a given group, deployment, or ecosystem anyway. This makes sense when you’ve got something reusable across many deployments, like OIDC, but it’s overhead when what you’re doing is tied to your environment.

3) This allows the AS and RS to define the request parameters for their APIs just like they do today with scopes. Since it’s always the combination of “this type :AT: this AS/RS”, name spacing is less of an issue across systems. We haven’t seen huge problems in scope value overlap in the wild, though it does occur from time to time it’s more than manageable. A client isn’t going to just “speak RAR”, it’s going to be speaking RAR so that it can access something in particular.

And all that brings me to my proposal: 

4) Require all values to be defined by the AS, and encourage specification developers to use URIs for collision resistance.

So officially in RAR, the AS would decide what “type” means, and nobody else. But we can also guide people who are developing general-purpose interoperable APIs to use URIs for their RAR “type” definitions. This would keep those interoperable APIs from stepping on each other, and from stepping on any locally-defined special “type” structure. But at the end of the day, the URI carries no more weight than just any other string, and the AS decides what it means and how it applies.

My argument is that this seems to have worked very, very well for scopes, and the RAR “type” is cut from similar descriptive cloth.

What does the rest of the group think? How should we manage the RAR “type” values and what they mean?

 — Justin

---

From: Dick Hardt <[email-masked]>
Date: Fri, 17 Jul 2020 10:25:19 -0700

Hey Justin, glad to see that you have aligned with the latest XAuth draft
on a type property being required.

I like the idea that the value of the type property is fully defined by the
AS, which could delegate it to a common URI for reuse. This gets GNAP out
of specifying access requests, and enables other parties to define access
without any required coordination with IETF or IANA.

A complication in mixing plain strings and URIs is the canonicalization. A
plain string can be a fixed byte representation, but a URI requires
canonicalization for comparison. Mixing the two requires URI detection at
the AS before canonicalization, and an AS MUST do canonicalization of URIs.

The URI is retrievable, it can provide machine and/or human readable
documentation in JSON schema or some such, or any other content type. Once
again, the details are out of scope of GNAP, but we can provide examples to
guide implementers.

Are you still thinking that bare strings are allowed in GNAP, and are
defined by the AS?

On Fri, Jul 17, 2020 at 8:39 AM Justin Richer <[email-masked]> wrote:

> The “type” field in the RAR spec serves an important purpose: it defines
> what goes in the rest of the object, including what other fields are
> available and what values are allowed for those fields. It provides an
> API-level definition for requesting access based on multiple dimensions,
> and that’s really powerful and flexible. Each type can use any of the
> general-purpose fields like “actions” and/or add its own fields as
> necessary, and the “type” parameter keeps everything well-defined.
>
> The question, then, is what defines what’s allowed to go into the “type”
> field itself? And what defines how that value maps to the requirements for
> the rest of the object? The draft doesn’t say anything about it at the
> moment, but we should choose the direction we want to go. On the surface,
> there are three main options:
>
> 1) While it usually makes sense to register things for interoperability,
> this is a case where I think that a registry would actually hurt
> interoperability and adoption. Like a “scope” value, the RAR “type” is
> ultimately up to the AS and RS to interpret in their own context. We :want:
> people to define rich objects for their APIs and enable fine-grained access
> for their systems, and if they have to register something every time they
> come up with a new API to protect, it’s going to be an unmaintainable mess.
> I genuinely don’t think this would scale, and that most developers would
> just ignore the registry and do what they want anyway. And since many of
> these systems are inside domains, it’s completely unenforceable in practice.
>
> 2) This seems reasonable, but it’s a bit of a nuisance to require
> everything to be a URI here. It’s long and ugly, and a lot of APIs are
> going to be internal to a given group, deployment, or ecosystem anyway.
> This makes sense when you’ve got something reusable across many
> deployments, like OIDC, but it’s overhead when what you’re doing is tied to
> your environment.
>
> 3) This allows the AS and RS to define the request parameters for their
> APIs just like they do today with scopes. Since it’s always the combination
> of “this type :AT: this AS/RS”, name spacing is less of an issue across
> systems. We haven’t seen huge problems in scope value overlap in the wild,
> though it does occur from time to time it’s more than manageable. A client
> isn’t going to just “speak RAR”, it’s going to be speaking RAR so that it
> can access something in particular.
>
> 4) Require all values to be defined by the AS, and encourage specification
> developers to use URIs for collision resistance.
>
> So officially in RAR, the AS would decide what “type” means, and nobody
> else. But we can also guide people who are developing general-purpose
> interoperable APIs to use URIs for their RAR “type” definitions. This would
> keep those interoperable APIs from stepping on each other, and from
> stepping on any locally-defined special “type” structure. But at the end of
> the day, the URI carries no more weight than just any other string, and the
> AS decides what it means and how it applies.
>
> My argument is that this seems to have worked very, very well for scopes,
> and the RAR “type” is cut from similar descriptive cloth.
>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>

---

From: Vladimir Dzhuvinov <[email-masked]>
Date: Fri, 17 Jul 2020 20:13:48 +0200

> So officially in RAR, the AS would decide what “type” means, and nobody else. But we can also guide people who are developing general-purpose interoperable APIs to use URIs for their RAR “type” def…

Define, but not publish in AS metadata?

> My argument is that this seems to have worked very, very well for scopes, and the RAR “type” is cut from similar descriptive cloth.

I would argue that it didn't work so well for scopes - the OAuth
Resource Indicators spec is a testament to that.

But one could also argue that scopes were not defined along the lines of
your proposal for "type" in RAR. In fact, RFC 6749 has no mention of
collision resistance or name spacing for scope values.

Vladimir

---

From: Justin Richer <[email-masked]>
Date: Sat, 18 Jul 2020 11:10:18 -0400

Hi Dick,

This is a discussion about the RAR specification on the OAuth list, and therefore doesn’t have anything to do with alignment with XAuth. In fact, I believe the alignment is the other way around, as doesn’t Xauth normatively reference RAR at this point? Even though, last I saw, it uses a different top-level structure for conveying things, I believe it does say to use the internal object structures. I am also a co-author on RAR and we had already defined a “type” field in RAR quite some time ago. You did notice that XYZ’s latest draft added this field to keep the two in alignment with each other, which has always been the goal since the initial proposal of the RAR work, but that’s a time lag and not a display of new intent. 

In any event, even though I think the decision has bearing in both places, this isn’t about GNAP. Working on RAR’s requirements has brought up this interesting issue of what should be in the type field for RAR in OAuth 2.

I think that it should be defined as a string, and therefore compared as a byte value in all cases, regardless of what the content of the string is. I don’t think the AS should be expected to fetch a URI for anything. I don’t think the AS should normalize any of the inputs. I think that any JSON-friendly character set should be allowed (including spaces and unicodes), and since RAR already requires the JSON objects to be form-encoded, this shouldn’t cause additional trouble when adding them in to OAuth 2’s request structures.

The idea of using a URI would be to get people out of each other’s namespaces. It’s similar to the concept of “public” vs “private” claims in JWT:

https://tools.ietf.org/html/rfc7519#section-4.2 <https://tools.ietf.org/html/rfc7519#section-4.2>

What I’m proposing is that if you think it’s going to be a general-purpose type name, then we recommend you use a URI as your string. And beyond that, that’s it. It’s up to the AS to figure out what to do with it, and RAR stays out of it.

 — Justin

> On Jul 17, 2020, at 1:25 PM, Dick Hardt <[email-masked]> wrote:
> 
> Hey Justin, glad to see that you have aligned with the latest XAuth draft on a type property being required.
> 
> I like the idea that the value of the type property is fully defined by the AS, which could delegate it to a common URI for reuse. This gets GNAP out of specifying access requests, and enables other parties to define access without any required coordination with IETF or IANA.
> 
> A complication in mixing plain strings and URIs is the canonicalization. A plain string can be a fixed byte representation, but a URI requires canonicalization for comparison. Mixing the two requires URI detection at the AS before canonicalization, and an AS MUST do canonicalization of URIs.
> 
> The URI is retrievable, it can provide machine and/or human readable documentation in JSON schema or some such, or any other content type. Once again, the details are out of scope of GNAP, but we can provide examples to guide implementers.
> 
> Are you still thinking that bare strings are allowed in GNAP, and are defined by the AS?
> 
> 
> 
> On Fri, Jul 17, 2020 at 8:39 AM Justin Richer <[email-masked] <mailto:[email-masked]>> wrote:
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/oauth <https://www.ietf.org/mailman/listinfo/oauth>

---

From: Justin Richer <[email-masked]>
Date: Sat, 18 Jul 2020 11:12:57 -0400

I think publishing supported “type” parameters isn’t a bad idea, and it aligns with publishing supported scopes and claims in discovery.

I have always seen the resource indicators work as providing a more specific dimension to the requests that scopes didn’t allow to be described very well, pointing at a specific RS instead of just “some kind of access”, so I’m not sure how they’re a testament to name spacing issues with scopes. Can you help me understand here?

I do think that if nothing else we can give better guidance in RAR as to what the “type” field is. I do think it should still just be a string, but we can help people make better decisions about what to put in that string.

 — Justin

> On Jul 17, 2020, at 2:13 PM, Vladimir Dzhuvinov <[email-masked]> wrote:
> 
>

---

From: Dick Hardt <[email-masked]>
Date: Sat, 18 Jul 2020 17:58:23 -0700

Justin: thanks for kindly pointing out which mail list this is.

To clarify, public JWT claims are not just URIs, but any
collision-resistant namespace:
"Examples of collision-resistant namespaces include: Domain Names, Object
Identifiers (OIDs) as defined in the ITU-T X.660 and      X.670
Recommendation series, and Universally Unique IDentifiers (UUIDs)
[RFC4122]."

I think letting the "type" be any JSON string and doing a byte-wise
comparison will be problematic. A client developer will be reading
documentation to learn what the types are, and typing it in. Given the wide
set of whitespace characters, and unicode equivalence, different byte
streams will all look the same, and a byte-wise comparison will fail.

Similarly for URIs. If it is a valid URI, then a byte-wise comparison is
not sufficient. Canonicalization is required.

These are not showstopper issues, but the specification should call out how
type strings are compared, and provide caveats to an AS developer.

I have no idea why you would think the AS would retrieve a URL.

Since the type represents a much more complex object then a JWT claim, a
client developer's tooling could pull down the JSON Schema (or some such)
for a type used in their source code, and provide autocompletion and
validation which would improve productivity and reduce errors. An AS that
is using a defined type could use the schema for input validation. Neither
of these would be at run time. JSON Schema allows comments and examples.

What is the harm in non-normative language around a retrievable URI?

BTW: the example in
https://oauth.xyz/draft-richer-transactional-authz#rfc.section.2 has not
been updated with the "type" field.

On Sat, Jul 18, 2020 at 8:10 AM Justin Richer <[email-masked]> wrote:

> Hi Dick,
>
> This is a discussion about the RAR specification on the OAuth list, and
> therefore doesn’t have anything to do with alignment with XAuth. In fact, I
> believe the alignment is the other way around, as doesn’t Xauth normatively
> reference RAR at this point? Even though, last I saw, it uses a different
> top-level structure for conveying things, I believe it does say to use the
> internal object structures. I am also a co-author on RAR and we had already
> defined a “type” field in RAR quite some time ago. You did notice that
> XYZ’s latest draft added this field to keep the two in alignment with each
> other, which has always been the goal since the initial proposal of the RAR
> work, but that’s a time lag and not a display of new intent.
>
> In any event, even though I think the decision has bearing in both places,
> this isn’t about GNAP. Working on RAR’s requirements has brought up this
> interesting issue of what should be in the type field for RAR in OAuth 2.
>
> I think that it should be defined as a string, and therefore compared as a
> byte value in all cases, regardless of what the content of the string is. I
> don’t think the AS should be expected to fetch a URI for anything. I don’t
> think the AS should normalize any of the inputs. I think that any
> JSON-friendly character set should be allowed (including spaces and
> unicodes), and since RAR already requires the JSON objects to be
> form-encoded, this shouldn’t cause additional trouble when adding them in
> to OAuth 2’s request structures.
>
> The idea of using a URI would be to get people out of each other’s
> namespaces. It’s similar to the concept of “public” vs “private” claims in
> JWT:
>
> https://tools.ietf.org/html/rfc7519#section-4.2
>
> What I’m proposing is that if you think it’s going to be a general-purpose
> type name, then we recommend you use a URI as your string. And beyond that,
> that’s it. It’s up to the AS to figure out what to do with it, and RAR
> stays out of it.
>
>  — Justin
>
> I like the idea that the value of the type property is fully defined by
> the AS, which could delegate it to a common URI for reuse. This gets GNAP
> out of specifying access requests, and enables other parties to define
> access without any required coordination with IETF or IANA.
>
>> 4) Require all values to be defined by the AS, and encourage
>> specification developers to use URIs for collision resistance.
>>

---

From: Vladimir Dzhuvinov <[email-masked]>
Date: Sun, 19 Jul 2020 19:04:48 +0200

> I think publishing supported “type” parameters isn’t a bad idea, and it aligns with publishing supported scopes and claims in discovery.

If you are a developer, would you like to be able to find out if the
authorization_details for a given "type" has a JSON schema and what it
looks like?

> I have always seen the resource indicators work as providing a more specific dimension to the requests that scopes didn’t allow to be described very well, pointing at a specific RS instead of just…

Putting the scopes for each RS in a unique name space, for example by
giving them a URI prefix which identifies the RS, can make the resource
indication redundant.

RS: https://some-rs.example.com/

RS scopes: read, update, delete

->

https://some-rs.example.com/read

https://some-rs.example.com/update

https://some-rs.example.com/delete

This will not work if the chosen name spacing pattern can produce
ambiguities, e.g. if https://rs.example.com/accounts and
https://rs.example.com/accounts/v1 are two different RSes.

I have witnessed situations when an AS is given some application to deal
with, with hard-wired scope values that have no name spacing, and to
prevent potential collisions with other applications, Resource
Indicators had to come to the rescue.

I also remember one case with an application having a scope name which
is also used for the OIDC userinfo endpoint.

> I do think that if nothing else we can give better guidance in RAR as to what the “type” field is. 

+1

> I do think it should still just be a string, but we can help people make better decisions about what to put in that string.

I'm still on the fence with that but I do see your argument.

Vladimir

-- 
Vladimir Dzhuvinov

---

From: Justin Richer <[email-masked]>
Date: Mon, 20 Jul 2020 07:42:27 -0400

Since this is a recommendation for namespace, we could also just say collision-resistant like JWT, and any of those examples are fine. But that said, I think there’s something particularly compelling about URIs since they have somewhat-human-readable portions. But again, I’m saying it should be a recommendation to API developers and not a requirement in the spec. In the spec, I argue that “type” should be a string, full stop.

If documentation is so confusing that developers are typing in the wrong strings, then that’s bad documentation. And likely a bad choice for the “type” string on the part of the AS. You’d have the same problem with any other value the developer’s supposed to copy over.  :)

I agree that we should call out explicitly how they should be compared, and I propose we use one of the handful of existing string-comparison RFC’s here instead of defining our own rules.

While the type could be a dereferenceable URI, requiring action on the AS is really getting into distributed authorization policies. We tried doing that with UMA1’s scope structures and it didn’t work very well in practice (in my memory and experience). Someone could profile “type" on top of this if they wanted to do so, with support at the AS for that, but I don’t see a compelling reason for that to be a requirement as that’s a lot of complexity and a lot more error states (the fetch fails, or it doesn’t have a policy, or the policy’s in a format the AS doesn’t understand, or the AS doesn’t like the policy, etc). 

And AS is always free to implement its types in such a fashion, and that could make plenty of sense in a smaller ecosystem. And this is yet another reason that we define “type” as being a string to be interpreted and understood by the AS — so that an AS that wants to work this way can do so.

 — Justin

PS: thanks for pointing out the error in the example in XYZ, I’ll fix that prior to publication.

> On Jul 18, 2020, at 8:58 PM, Dick Hardt <[email-masked]> wrote:
> 
> To clarify, public JWT claims are not just URIs, but any collision-resistant namespace: 
> "Examples of collision-resistant namespaces include: Domain Names, Object Identifiers (OIDs) as defined in the ITU-T X.660 and      X.670 Recommendation series, and Universally Unique IDentifiers (UUIDs) [RFC4122]."
> 
> I think letting the "type" be any JSON string and doing a byte-wise comparison will be problematic. A client developer will be reading documentation to learn what the types are, and typing it in. Given the wide set of whitespace characters, and unicode equivalence, different byte streams will all look the same, and a byte-wise comparison will fail.
> 
> Similarly for URIs. If it is a valid URI, then a byte-wise comparison is not sufficient. Canonicalization is required. 
> 
> These are not showstopper issues, but the specification should call out how type strings are compared, and provide caveats to an AS developer.
> 
> Since the type represents a much more complex object then a JWT claim, a client developer's tooling could pull down the JSON Schema (or some such) for a type used in their source code, and provide autocompletion and validation which would improve productivity and reduce errors. An AS that is using a defined type could use the schema for input validation. Neither of these would be at run time. JSON Schema allows comments and examples.
> 
> BTW: the example in https://oauth.xyz/draft-richer-transactional-authz#rfc.section.2 <https://oauth.xyz/draft-richer-transactional-authz#rfc.section.2> has not been updated with the "type" field.
> 
> 
> 
> On Sat, Jul 18, 2020 at 8:10 AM Justin Richer <[email-masked] <mailto:[email-masked]>> wrote:
> Hi Dick,
> 
>> On Jul 17, 2020, at 1:25 PM, Dick Hardt <[email-masked] <mailto:[email-masked]>> wrote:
>>

---

From: Justin Richer <[email-masked]>
Date: Mon, 20 Jul 2020 12:00:20 -0400

I created a pull request with some proposed language here:

https://github.com/oauthstuff/draft-oauth-rar/pull/52 <https://github.com/oauthstuff/draft-oauth-rar/pull/52>

 — Justin

> On Jul 20, 2020, at 7:42 AM, Justin Richer <[email-masked]> wrote:
> 
>> On Jul 18, 2020, at 8:58 PM, Dick Hardt <[email-masked] <mailto:[email-masked]>> wrote:
>>

---

From: Dick Hardt <[email-masked]>
Date: Mon, 20 Jul 2020 11:59:16 -0700

Canonicalization of URIs and unicode is fairly well specified. I was not
suggesting we invent anything there.

A byte comparison, as you suggested earlier, will be problematic, as I have
pointed out.

I'm confused why you are still talking about the AS retrieving a URI.

ᐧ

On Mon, Jul 20, 2020 at 4:42 AM Justin Richer <[email-masked]> wrote:

> Since this is a recommendation for namespace, we could also just say
> collision-resistant like JWT, and any of those examples are fine. But that
> said, I think there’s something particularly compelling about URIs since
> they have somewhat-human-readable portions. But again, I’m saying it should
> be a recommendation to API developers and not a requirement in the spec. In
> the spec, I argue that “type” should be a string, full stop.
>
> If documentation is so confusing that developers are typing in the wrong
> strings, then that’s bad documentation. And likely a bad choice for the
> “type” string on the part of the AS. You’d have the same problem with any
> other value the developer’s supposed to copy over.  :)
>
> I agree that we should call out explicitly how they should be compared,
> and I propose we use one of the handful of existing string-comparison RFC’s
> here instead of defining our own rules.
>
> While the type could be a dereferenceable URI, requiring action on the AS
> is really getting into distributed authorization policies. We tried doing
> that with UMA1’s scope structures and it didn’t work very well in practice
> (in my memory and experience). Someone could profile “type" on top of this
> if they wanted to do so, with support at the AS for that, but I don’t see a
> compelling reason for that to be a requirement as that’s a lot of
> complexity and a lot more error states (the fetch fails, or it doesn’t have
> a policy, or the policy’s in a format the AS doesn’t understand, or the AS
> doesn’t like the policy, etc).
>
> And AS is always free to implement its types in such a fashion, and that
> could make plenty of sense in a smaller ecosystem. And this is yet another
> reason that we define “type” as being a string to be interpreted and
> understood by the AS — so that an AS that wants to work this way can do so.
>
>  — Justin
>
> These are not showstopper issues, but the specification should call out
> how type strings are compared, and provide caveats to an AS developer.
>
>> In any event, even though I think the decision has bearing in both
>> places, this isn’t about GNAP. Working on RAR’s requirements has brought up
>> this interesting issue of what should be in the type field for RAR in OAuth
>> 2.
>>
>> I think that it should be defined as a string, and therefore compared as
>> a byte value in all cases, regardless of what the content of the string is.
>> I don’t think the AS should be expected to fetch a URI for anything. I
>> don’t think the AS should normalize any of the inputs. I think that any
>> What I’m proposing is that if you think it’s going to be a
>> general-purpose type name, then we recommend you use a URI as your string.
>> And beyond that, that’s it. It’s up to the AS to figure out what to do with
>> it, and RAR stays out of it.
>>
>>  — Justin
>>
>> A complication in mixing plain strings and URIs is the canonicalization.
>> A plain string can be a fixed byte representation, but a URI requires
>>> My argument is that this seems to have worked very, very well for
>>> scopes, and the RAR “type” is cut from similar descriptive cloth.
>>>

---

From: Justin Richer <[email-masked]>
Date: Tue, 21 Jul 2020 10:35:47 -0400

If we treat all the strings as just strings, without any special internal format to be specified or detected, then comparing the strings is a well-understood and well-documented process. I also think that we shouldn’t invent anything here, so if there’s a better way to say “compare two strings so that they’re exact” then that’s what I mean. Sorry if that was unclear.

I’m saying the AS should not retrieve the URI passed in the “type” value. You brought that up and then described the process that the AS would take to do so. I have said from the start that the use of a URI is for name spacing and not for addressing content to be fetched, so I’m confused why you think I intend otherwise.

 — Justin

> On Jul 20, 2020, at 2:59 PM, Dick Hardt <[email-masked]> wrote:
> 
> Canonicalization of URIs and unicode is fairly well specified. I was not suggesting we invent anything there.
> 
> A byte comparison, as you suggested earlier, will be problematic, as I have pointed out.
> 
> On Mon, Jul 20, 2020 at 4:42 AM Justin Richer <[email-masked] <mailto:[email-masked]>> wrote:

---

From: Justin Richer <[email-masked]>
Date: Tue, 21 Jul 2020 10:47:26 -0400

> On Jul 19, 2020, at 1:04 PM, Vladimir Dzhuvinov <[email-masked]> wrote:
> 
> If you are a developer, would you like to be able to find out if the authorization_details for a given "type" has a JSON schema and what it looks like?
> 
> 
> 
I think that would be a nice thing for an AS/API to offer, but I don’t think it should be expected or required here. That might be a good note in the guidance, say that if you use a URI for your “type” field then it would be nice if it resolved to something either human or machine readable. What I don’t want is for us to require every AS to have to resolve these URIs in order to process and understand them. That’s why I’m taking the position of it being a string, and the URI can provide disambiguation in the way you’re talking about below.

> Putting the scopes for each RS in a unique name space, for example by giving them a URI prefix which identifies the RS, can make the resource indication redundant.
> 
> RS: https://some-rs.example.com/ <https://some-rs.example.com/>
> 
> https://some-rs.example.com/read <https://some-rs.example.com/read>
> https://some-rs.example.com/update <https://some-rs.example.com/update>
> https://some-rs.example.com/delete <https://some-rs.example.com/delete>
> This will not work if the chosen name spacing pattern can produce ambiguities, e.g. if https://rs.example.com/accounts <https://rs.example.com/accounts> and https://rs.example.com/accounts/v1 <https://rs.example.com/accounts/v1> are two different RSes.
> 
> 
> 
> I have witnessed situations when an AS is given some application to deal with, with hard-wired scope values that have no name spacing, and to prevent potential collisions with other applications, Resource Indicators had to come to the rescue.
> 
That only really works if you are asking for multiple tokens for different resources. With RAR we can at least group things together, and so things like the read/update/delete can now be under the “actions” field with “https://some-rs.example.com/ <https://some-rs.example.com/>“ be the “type” field. Or even better, “https://some-rs-example.com/ <https://some-rs-example.com/>“ is the “locations” value and the “type” is something like “https://rs.example.com/accounts <https://rs.example.com/accounts>”. Since things get combined inside an object with distinct fields, and not as substrings and prefixes, we don’t have the ambiguity with “https://rs.example.com/accounts/v1 <https://rs.example.com/accounts/v1>” anymore. As a note we would also treat “https://rs.example.com/accounts/ <https://rs.example.com/accounts/>“ (with a trailing slash) as a distinct “type” value under this logic.
> I also remember one case with an application having a scope name which is also used for the OIDC userinfo endpoint.
> 
> 
> 
This is exactly the kind of thing that I think we can do better to avoid here. So I would expect a protocol like OIDC to use something like “https://openid.net/specs/connect/ <https://openid.net/specs/connect/>userinfo“ as its “type” field, since it’s coming from a standards body and is meant to be used by many different systems. But if I’ve also got some custom internal timecard API I would just use “timecard” as the “type” there, since it’s internal to just that one AS. And if both of these have an “email” value for, say, “datatype”, then they don’t overlap with each other.
> I'm still on the fence with that but I do see your argument.

Thanks for the feedback!

 — Justin

> Vladimir
> 
> 
> 
>>  — Justin
>> 
>>> On Jul 17, 2020, at 2:13 PM, Vladimir Dzhuvinov <[email-masked]> <mailto:[email-masked]> wrote:
>>> 
>>>

---

From: Vladimir Dzhuvinov <[email-masked]>
Date: Tue, 21 Jul 2020 18:40:07 +0300

On 21/07/2020 17:47, Justin Richer wrote:
>> On Jul 19, 2020, at 1:04 PM, Vladimir Dzhuvinov
>> <[email-masked] <mailto:[email-masked]>> wrote:
>>
>> authorization_details for a given "type" has a JSON schema and what
>> it looks like?
>>
>>
> I think that would be a nice thing for an AS/API to offer, but I don’t
> think it should be expected or required here. That might be a good
> note in the guidance, say that if you use a URI for your “type” field
> then it would be nice if it resolved to something either human or
> machine readable. What I don’t want is for us to require every AS to
> have to resolve these URIs in order to process and understand them.
> That’s why I’m taking the position of it being a string, and the URI
> can provide disambiguation in the way you’re talking about below.

We've been thinking about giving developers the possibility to discover
the authorization_details JSON schema (if one is supplied) for a given
type via a separate AS metadata parameter. Not by making the type a
dereferceable URL, which will overload things too much.

authorization_details_json_schemas : {

    "<type-a>" : "<type-a-json-schema-url>",

    "<type-b>" : "<type-b-json-schema-url>",

   ...

}

The rationale -- to minimise the number of potential support calls for
providers arising from "Oh dear, why do I get this invalid_request
now..." with complex RAR JSON objects.

Vladimir

---

From: Torsten Lodderstedt <[email-masked]>
Date: Tue, 21 Jul 2020 17:43:06 +0200

> On 21. Jul 2020, at 17:40, Vladimir Dzhuvinov <[email-masked]> wrote:
> 
> 
> 
> We've been thinking about giving developers the possibility to discover the authorization_details JSON schema (if one is supplied) for a given type via a separate AS metadata parameter. Not by making the type a dereferceable URL, which will overload things too much.
> 
> The rationale -- to minimise the number of potential support calls for providers arising from "Oh dear, why do I get this invalid_request now..." with complex RAR JSON objects.

We could borrow the "$schema” element. 

However, I’m on the fence regarding introducing a separate parameter for the schema simply because it also introduce a new error cause if type and schema are inconsistent. 

best regards,
Torsten.

---

From: Dick Hardt <[email-masked]>
Date: Tue, 21 Jul 2020 09:35:14 -0700

This statement:

“compare two strings so that they’re exact”

does not work for either Unicode or URIs. A string, and a canonicalized
Unicode string are not the same thing. Similar for a URI. I have assumed
you understand the canonicalization requirement, but it does not sound like
you do. Would you like examples?

wrt. the AS and URI, *you* keep saying that *I* said the AS would retrieve
the URI. I HAVE NOT SAID THAT!

I am suggesting that the URI MAY be retrievable, and I gave examples on how
that would be useful for tooling for client developers, and for an AS in
doing input validation. The URI would NOT be retrieved at run time.

On Tue, Jul 21, 2020 at 7:35 AM Justin Richer <[email-masked]> wrote:

> If we treat all the strings as just strings, without any special internal
> format to be specified or detected, then comparing the strings is a
> well-understood and well-documented process. I also think that we shouldn’t
> invent anything here, so if there’s a better way to say “compare two
> strings so that they’re exact” then that’s what I mean. Sorry if that was
> unclear.
>
> I’m saying the AS should *not* retrieve the URI passed in the “type”
> value. You brought that up and then described the process that the AS would
> take to do so. I have said from the start that the use of a URI is for name
> spacing and not for addressing content to be fetched, so I’m confused why
> you think I intend otherwise.
>
>  — Justin
>
>>>> The “type” field in the RAR spec serves an important purpose: it
>>>> defines what goes in the rest of the object, including what other fields
>>>> are available and what values are allowed for those fields. It provides an
>>>> The question, then, is what defines what’s allowed to go into the
>>>> “type” field itself? And what defines how that value maps to the
>>>> requirements for the rest of the object? The draft doesn’t say anything
>>>> about it at the moment, but we should choose the direction we want to go.
>>>> On the surface, there are three main options:
>>>>
>>>> 1) While it usually makes sense to register things for
>>>> interoperability, this is a case where I think that a registry would
>>>> actually hurt interoperability and adoption. Like a “scope” value, the RAR
>>>> “type” is ultimately up to the AS and RS to interpret in their own context.
>>>> We :want: people to define rich objects for their APIs and enable
>>>> fine-grained access for their systems, and if they have to register
>>>> something every time they come up with a new API to protect, it’s going to
>>>> be an unmaintainable mess. I genuinely don’t think this would scale, and
>>>> that most developers would just ignore the registry and do what they want
>>>> anyway. And since many of these systems are inside domains, it’s completely
>>>> unenforceable in practice.
>>>>

---

From: Justin Richer <[email-masked]>
Date: Tue, 21 Jul 2020 12:58:08 -0400

String comparison works just fine when the strings happen to be URIs, and you aren’t treating them as URIs:

	“https://schema.example.org/v1”

Is different from 

	“https://schema.example.org/v2”

And both are different from

	“https://schema.example.org:443/v1/“

All of these are strings, and the strings happen to be URIs but that’s irrelevant to the comparison process. Can you please help me understand why doing a string comparison on these values does not work in exactly the same way it would for “foo”, “bar”, and “baz” values? Why would these need to be canonicalized to be compared? The definition of a JSON string is an ordered set of unicode code points, and this can be compared byte-wise. (Or code-point-wise, whatever’s most correct here.) Can you give me counter-examples as to where string comparison doesn’t work? And can you help me understand how this same worry doesn’t apply to all of the rest of the values in the RAR specification, which are also strings and will need to be compared?

I’m still very confused as to the URI retrieval issue here, if there even is one. It sounds like we’re both saying that it could be useful if type values are retrievable when they’re URIs, but that would be something to augment a process and not required for the RAR spec. I’m against requiring the value to be a URI and against requiring the AS to process that URI as a URI at runtime. Anything that an AS wants to do with the “type” value, including providing additional tooling and validation, is up to the AS and outside of the spec.

 — Justin

> On Jul 21, 2020, at 12:35 PM, Dick Hardt <[email-masked]> wrote:
> 
> This statement:
> 
> does not work for either Unicode or URIs. A string, and a canonicalized Unicode string are not the same thing. Similar for a URI. I have assumed you understand the canonicalization requirement, but it does not sound like you do. Would you like examples?
> 
> 
> wrt. the AS and URI, *you* keep saying that *I* said the AS would retrieve the URI. I HAVE NOT SAID THAT!
> 
> I am suggesting that the URI MAY be retrievable, and I gave examples on how that would be useful for tooling for client developers, and for an AS in doing input validation. The URI would NOT be retrieved at run time.
> 
> 
> On Tue, Jul 21, 2020 at 7:35 AM Justin Richer <[email-masked] <mailto:[email-masked]>> wrote:
>> On Jul 20, 2020, at 2:59 PM, Dick Hardt <[email-masked] <mailto:[email-masked]>> wrote:
>>

---

From: Dick Hardt <[email-masked]>
Date: Tue, 21 Jul 2020 10:03:45 -0700

The following are the same URI, but are different strings:

“https://schema.example.org/v1”
“HTTPS://schema.example.org/v1 <https://schema.example.org/v1>”
“https://SCHEMA.EXAMPLE.ORG/v1 <https://schema.example.org/v1>”

Before comparing them to each other, they must be canonicalized so that
they become the same string.

>From earlier in this thread, I am NOT suggesting that it must be a URI, nor
that it is required:

On Tue, Jul 21, 2020 at 9:58 AM Justin Richer <[email-masked]> wrote:

> All of these are strings, and the strings happen to be URIs but that’s
> irrelevant to the comparison process. Can you please help me understand why
> doing a string comparison on these values does not work in exactly the same
> way it would for “foo”, “bar”, and “baz” values? Why would these need to be
> canonicalized to be compared? The definition of a JSON string is an ordered
> set of unicode code points, and this can be compared byte-wise. (Or
> code-point-wise, whatever’s most correct here.) Can you give me
> counter-examples as to where string comparison doesn’t work? And can you
> help me understand how this same worry doesn’t apply to all of the rest of
> the values in the RAR specification, which are also strings and will need
> to be compared?
>
> I’m still very confused as to the URI retrieval issue here, if there even
> is one. It sounds like we’re both saying that it could be useful if type
> values are retrievable when they’re URIs, but that would be something to
> augment a process and not required for the RAR spec. I’m against requiring
> the value to be a URI and against requiring the AS to process that URI *as
> a URI* at runtime. Anything that an AS wants to do with the “type” value,
> including providing additional tooling and validation, is up to the AS and
> outside of the spec.
>
>  — Justin
>
> I am suggesting that the URI MAY be retrievable, and I gave examples on
> how that would be useful for tooling for client developers, and for an AS
> in doing input validation. The URI would NOT be retrieved at run time.
>
>
>>> While the type could be a dereferenceable URI, requiring action on the
>>> AS is really getting into distributed authorization policies. We tried
>>> doing that with UMA1’s scope structures and it didn’t work very well in
>>> practice (in my memory and experience). Someone could profile “type" on top
>>> of this if they wanted to do so, with support at the AS for that, but I
>>> don’t see a compelling reason for that to be a requirement as that’s a lot
>>> of complexity and a lot more error states (the fetch fails, or it doesn’t
>>> have a policy, or the policy’s in a format the AS doesn’t understand, or
>>> the AS doesn’t like the policy, etc).
>>>
>>> "Examples of collision-resistant namespaces include: Domain Names,
>>> Object Identifiers (OIDs) as defined in the ITU-T X.660 and      X.670
>>> https://oauth.xyz/draft-richer-transactional-authz#rfc.section.2 has
>>> not been updated with the "type" field.
>>>
>>>
>>>
>>>> I think that it should be defined as a string, and therefore compared
>>>> as a byte value in all cases, regardless of what the content of the string
>>>> is. I don’t think the AS should be expected to fetch a URI for anything. I
>>>> A complication in mixing plain strings and URIs is the
>>>> canonicalization. A plain string can be a fixed byte representation, but a
>>>> URI requires canonicalization for comparison. Mixing the two requires URI
>>>> detection at the AS before canonicalization, and an AS MUST do
>>>> canonicalization of URIs.
>>>>
>>>>> 3) This allows the AS and RS to define the request parameters for
>>>>> their APIs just like they do today with scopes. Since it’s always the
>>>>> combination of “this type :AT: this AS/RS”, name spacing is less of an
>>>>> issue across systems. We haven’t seen huge problems in scope value overlap
>>>>> in the wild, though it does occur from time to time it’s more than
>>>>> manageable. A client isn’t going to just “speak RAR”, it’s going to be
>>>>> speaking RAR so that it can access something in particular.
>>>>>
>>>>> So officially in RAR, the AS would decide what “type” means, and
>>>>> nobody else. But we can also guide people who are developing
>>>>> general-purpose interoperable APIs to use URIs for their RAR “type”
>>>>> definitions. This would keep those interoperable APIs from stepping on each
>>>>> other, and from stepping on any locally-defined special “type” structure.
>>>>> But at the end of the day, the URI carries no more weight than just any
>>>>> other string, and the AS decides what it means and how it applies.
>>>>>

---

From: Dick Hardt <[email-masked]>
Date: Tue, 21 Jul 2020 10:09:57 -0700

An explanation of the issues in Unicode can be found here:

https://en.wikipedia.org/wiki/Unicode_equivalence#Character_duplication

On Tue, Jul 21, 2020 at 10:03 AM Dick Hardt <[email-masked]> wrote:

> From earlier in this thread, I am NOT suggesting that it must be a URI,
> nor that it is required:
>
>> a URI* at runtime. Anything that an AS wants to do with the “type”
>> value, including providing additional tooling and validation, is up to the
>> AS and outside of the spec.
>>
>>  — Justin
>>
>>> If we treat all the strings as just strings, without any special
>>> internal format to be specified or detected, then comparing the strings is
>>> a well-understood and well-documented process. I also think that we
>>> shouldn’t invent anything here, so if there’s a better way to say “compare
>>> two strings so that they’re exact” then that’s what I mean. Sorry if that
>>> was unclear.
>>>
>>>> If documentation is so confusing that developers are typing in the
>>>> wrong strings, then that’s bad documentation. And likely a bad choice for
>>>> the “type” string on the part of the AS. You’d have the same problem with
>>>> any other value the developer’s supposed to copy over.  :)
>>>>
>>>> And AS is always free to implement its types in such a fashion, and
>>>> that could make plenty of sense in a smaller ecosystem. And this is yet
>>>> another reason that we define “type” as being a string to be interpreted
>>>> and understood by the AS — so that an AS that wants to work this way can do
>>>> so.
>>>>
>>>>  — Justin
>>>>
>>>> Similarly for URIs. If it is a valid URI, then a byte-wise comparison
>>>> is not sufficient. Canonicalization is required.
>>>>
>>>> Since the type represents a much more complex object then a JWT claim,
>>>> a client developer's tooling could pull down the JSON Schema (or some such)
>>>>> This is a discussion about the RAR specification on the OAuth list,
>>>>> and therefore doesn’t have anything to do with alignment with XAuth. In
>>>>> fact, I believe the alignment is the other way around, as doesn’t Xauth
>>>>> normatively reference RAR at this point? Even though, last I saw, it uses a
>>>>> different top-level structure for conveying things, I believe it does say
>>>>> to use the internal object structures. I am also a co-author on RAR and we
>>>>> had already defined a “type” field in RAR quite some time ago. You did
>>>>> notice that XYZ’s latest draft added this field to keep the two in
>>>>> alignment with each other, which has always been the goal since the initial
>>>>> proposal of the RAR work, but that’s a time lag and not a display of new
>>>>> intent.
>>>>>
>>>>> I like the idea that the value of the type property is fully defined
>>>>> by the AS, which could delegate it to a common URI for reuse. This gets
>>>>> GNAP out of specifying access requests, and enables other parties to define

---

From: Justin Richer <[email-masked]>
Date: Tue, 21 Jul 2020 13:34:25 -0400

Right, and I’m saying that all three of those would be DIFFERENT “type” values, because they’re different strings. The fact that when treated as URIs they would be equivalent is irrelevant. Just like “foo”, “Foo”, and “FOO” would be different “type” values, per the spec. Nothing is stopping an AS from treating them as equivalent internally, but that seems a bit dangerous to me. I’d love to see a formal breakdown of that, though.

As for the unicode example, if we define things as using byte comparisons, then that becomes an issue for proper documentation and configuration — and again, probably a good place to have recommendations for picking type value strings so as to avoid such problems.

In short, I don’t think we should have any requirements on canonicalization for these values.

 — Justin

> On Jul 21, 2020, at 1:03 PM, Dick Hardt <[email-masked]> wrote:
> 
> 
> 	“https://schema.example.org/v1 <https://schema.example.org/v1>”
> Before comparing them to each other, they must be canonicalized so that they become the same string.
> 
> From earlier in this thread, I am NOT suggesting that it must be a URI, nor that it is required:
> 
> On Tue, Jul 21, 2020 at 9:58 AM Justin Richer <[email-masked] <mailto:[email-masked]>> wrote:
> 	“https://schema.example.org/v1 <https://schema.example.org/v1>”
> 
> Is different from 
> 
> 	“https://schema.example.org/v2 <https://schema.example.org/v2>”
> 
> 	“https://schema.example.org:443/v1 <https://schema.example.org/v1>/“
> 
>> On Jul 21, 2020, at 12:35 PM, Dick Hardt <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> This statement:
>>

---

From: Dick Hardt <[email-masked]>
Date: Tue, 21 Jul 2020 10:55:52 -0700

In unicode, a glyph can be represented by more than one code point. When
reading the docs and entering a value, the developer will not know which
code point the AS intended.

Are you suggesting that AS documentation would have the bytes rather than
glyphs? Or not use glyphs that have multiple code points? Or that they only
use english?

On Tue, Jul 21, 2020 at 10:34 AM Justin Richer <[email-masked]> wrote:

> Right, and I’m saying that all three of those would be DIFFERENT “type”
> values, because they’re different strings. The fact that when treated as
> URIs they would be equivalent is irrelevant. Just like “foo”, “Foo”, and
> “FOO” would be different “type” values, per the spec. Nothing is stopping
> an AS from treating them as equivalent internally, but that seems a bit
> dangerous to me. I’d love to see a formal breakdown of that, though.
>
> As for the unicode example, if we define things as using byte comparisons,
> then that becomes an issue for proper documentation and configuration — and
> again, probably a good place to have recommendations for picking type value
> strings so as to avoid such problems.
>

---

From: Justin Richer <[email-masked]>
Date: Tue, 21 Jul 2020 14:05:10 -0400

I’m suggesting that API designers avoid using such glyphs in their “type” values if they want to avoid such human-copy errors, like they would need to do for most other strings in their system. If that means they stick to ASCII or put a note on the developer page that says “hey copy and paste this value, don’t try to re-type it” or whatever, that’s up to the AS. 

You’d have the same kind of issue around “similar-looking” characters, like the semicolon vs. the greek question mark. Should the AS look for those and try to “fix” the inputs? I would argue not: the AS should be strict in matching these values because it could have security implications. 

This isn’t a problem unique to RAR, or OAuth for that matter. We can, and I think should, add guidance to the RAR document for all of these points. 

 — Justin

> On Jul 21, 2020, at 1:55 PM, Dick Hardt <[email-masked]> wrote:
> 
> In unicode, a glyph can be represented by more than one code point. When reading the docs and entering a value, the developer will not know which code point the AS intended. 
> 
> Are you suggesting that AS documentation would have the bytes rather than glyphs? Or not use glyphs that have multiple code points? Or that they only use english?
> 
> 
> 
> On Tue, Jul 21, 2020 at 10:34 AM Justin Richer <[email-masked] <mailto:[email-masked]>> wrote:
>> On Jul 21, 2020, at 1:03 PM, Dick Hardt <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>>

---

From: Joseph Heenan <[email-masked]>
Date: Tue, 21 Jul 2020 21:56:43 +0100

I’d agree with this. I’d probably go even further and suggest the specification simply disallow non-ASCII values - it just seems like a minefield that so many people have unsuccessfully attempted to negotiate, and it is not necessary to force or allow AS implementors (or the rest of the ecosystem) venture in there.

There’s really no strong reason to use/allow full Unicode for items that are only exposed to developers, and there are significant reasons for applying the KISS principle - it makes life easy for AS, for clients, and closes an entire possible attack vector.

Joseph

> On 21 Jul 2020, at 19:05, Justin Richer <[email-masked]> wrote:
> 
>> On Jul 21, 2020, at 1:55 PM, Dick Hardt <[email-masked] <mailto:[email-masked]>> wrote:
>>

---

From: Vladimir Dzhuvinov <[email-masked]>
Date: Wed, 22 Jul 2020 23:16:37 +0300

> We could borrow the "$schema” element. 

Could you elaborate?

> However, I’m on the fence regarding introducing a separate parameter for the schema simply because it also introduce a new error cause if type and schema are inconsistent. 

Another idea was to still let the AS be configured with optional JSON
schemas for each type, and if the schema check of the
authorization_details fails, to include a meaningful message in the
invalid_request error_description and the schema URL in the error_uri.

The downside of that is the schema cannot be discovered or retrieved
upfront.

We really want to make it easy for developers to debug their requests
when facing complex RARs, on their own, without having to rely on a
support desk.

IMO the std invalid_request is ok for communicating the condition of an
authorization_details object failing the schema check (if the additional
error code was your concern).

Vladimir

---

From: Torsten Lodderstedt <[email-masked]>
Date: Wed, 22 Jul 2020 23:02:54 +0200

> On 22. Jul 2020, at 22:16, Vladimir Dzhuvinov <[email-masked]> wrote:
> 
> 

I mean we could use this element in addition to the “type” element to specify the corresponding schema in each authorization details object.

---

From: Justin Richer <[email-masked]>
Date: Fri, 24 Jul 2020 16:51:01 -0400

The more I’ve been thinking about it, the more I like the idea of using “$schema” for that purpose. It’s already got a well-defined definition in the JSON Schema world that would be familiar to people doing that, and there’s no need to overload the “type” field for that purpose. You would be able to do the same thing with the “@context” field from JSONLD, which has similar semantics. If we tried to put those both into the “type” field, and AS would have a hard time supporting both types of APIs, and so our goal of allowing easy differentiation at the AS isn’t really met.

A quick straw man idea: 

We :could: define a value for “type” that is “https://schema.org/ <https://schema.org/>“ and have it define the “$schema” field and how to process the rest of the object using JSON Schema. Similar idea for something JSONLD based, it uses “https://json-ld.org <https://json-ld.org/>” and defines a “@context” field that says how to process the rest of the request object using JSON-LD.

And in all of these cases, the “type” field is always checked by the AS by doing a simple string comparison. The URI here is just to keep the two public spaces from stepping on each other in their definitions. 

As for Joseph’s comment about unicode: I think we can recommend that people use ASCII because of the usability concerns, and use string comparison to check and compare.

 — Justin

> On Jul 22, 2020, at 5:02 PM, Torsten Lodderstedt <torsten=[email-masked]> wrote:
> 
> 
>

---

From: Brian Campbell <[email-masked]>
Date: Fri, 24 Jul 2020 15:55:04 -0600

I think I'm on board with the type being a just string and the guidance
provided about collision-resistance (rather than having a registry for
types or requiring type to be a URI or something along those lines). I
don't believe there's actually an issue with string comparison in that
context and so see no need for the draft to say anything special about it.

In looking at the pull request, however, I'm surprised by there being a
registry for the data elements. And honestly confused about how that would
even work in practice. The contents of the authorization details
object are determined
by the `type` parameter but there's also a registry of the elements that
can make up that content that are general across type. I don't see how to
reconcile that.

On Mon, Jul 20, 2020 at 10:00 AM Justin Richer <[email-masked]> wrote:

> https://github.com/oauthstuff/draft-oauth-rar/pull/52
>
>  — Justin
>

-- 
_CONFIDENTIALITY NOTICE: This email may contain confidential and privileged 
material for the sole use of the intended recipient(s). Any review, use, 
distribution or disclosure by others is strictly prohibited.  If you have 
received this communication in error, please notify the sender immediately 
by e-mail and delete the message and any file attachments from your 
computer. Thank you._

---

From: Justin Richer <[email-masked]>
Date: Sat, 25 Jul 2020 20:47:51 -0400

Brian,

I can appreciate the confusion on the elements registry. It’s really about having a place to put re-usable components that people might use within their own “type” definitions, if they want to. The construct in use there is similar to what we used in Vectors of Trust (RFC8485), https://tools.ietf.org/html/rfc8485 <https://tools.ietf.org/html/rfc8485>

A VoT “trust framework” document can technically define whatever categories and values that it wants to. However, there is a registry for common categories, designed to be core dimensions applicable across a number of different trust frameworks. 

So the way that it works is that a “type” can redefine its own syntax and semantics for something like “actions” or “locations”, if it wants to, but the registry is giving people a place to look and say, “oh hey, someone already uses ‘actions’ in a general way, maybe that works for me and I can use that definition, or maybe I should find a different word”. So while “type” avoids the programmatic namespace collision of two different definitions of “action”, the registry helps to avoid developer confusion about having two different uses for the same word. 

It’s not foolproof, but it’s better than making every API designer start from a completely blank slate.

 — Justin

> On Jul 24, 2020, at 5:55 PM, Brian Campbell <[email-masked]> wrote:
> 
> I think I'm on board with the type being a just string and the guidance provided about collision-resistance (rather than having a registry for types or requiring type to be a URI or something along those lines). I don't believe there's actually an issue with string comparison in that context and so see no need for the draft to say anything special about it. 
> 
> In looking at the pull request, however, I'm surprised by there being a registry for the data elements. And honestly confused about how that would even work in practice. The contents of the authorization details object are determined by the `type` parameter but there's also a registry of the elements that can make up that content that are general across type. I don't see how to reconcile that. 
> 
> On Mon, Jul 20, 2020 at 10:00 AM Justin Richer <[email-masked] <mailto:[email-masked]>> wrote:
>> On Jul 20, 2020, at 7:42 AM, Justin Richer <[email-masked] <mailto:[email-masked]>> wrote:
>> 
> CONFIDENTIALITY NOTICE: This email may contain confidential and privileged material for the sole use of the intended recipient(s). Any review, use, distribution or disclosure by others is strictly prohibited.  If you have received this communication in error, please notify the sender immediately by e-mail and delete the message and any file attachments from your computer. Thank you.

---

From: Torsten Lodderstedt <[email-masked]>
Date: Sun, 26 Jul 2020 13:26:57 +0200

Hi,

the wording regarding type works for me.

Similar to Brian, I don’t understand how the data type registry is supposed to work.

In my opinion, type and locations are completely different from the other elements since they are required by the protocol itself. Their semantics must not be changed by applications.

The other element types are reusable components, but I don’t understand how an application or standard would refer to them, include them into there type definition, and how overloading might happen. For example, are these elements always included in the top level container or can they be used deeper in the structure?

There are alternative solutions for reuse. I personally would use JSON schemas to define such reusable elements and the authorization data types utilizing them. 

I therefore don’t see the need for a RAR specific mechanism (a registry).

best regards,
Torsten.

> Am 26.07.2020 um 02:48 schrieb Justin Richer <[email-masked]>:
> 
> Brian,
> 
> I can appreciate the confusion on the elements registry. It’s really about having a place to put re-usable components that people might use within their own “type” definitions, if they want to. The construct in use there is similar to what we used in Vectors of Trust (RFC8485), https://tools.ietf.org/html/rfc8485
> 
>>>>> BTW: the example in https://oauth.xyz/draft-richer-transactional-authz#rfc.section.2 has not been updated with the "type" field.
>>>>> 
>>>>> 
>>>>>

---

From: Justin Richer <[email-masked]>
Date: Mon, 27 Jul 2020 08:33:23 -0400

That’s fair — I think there’s value in reusable components but they don’t have to be controlled by a registry. I’ll back off the registry language for that bit and file an issue to that effect.

 — Justin

> On Jul 26, 2020, at 7:26 AM, Torsten Lodderstedt <[email-masked]> wrote:
> 
> Hi,
> 
>>> On Jul 24, 2020, at 5:55 PM, Brian Campbell <[email-masked] <mailto:[email-masked]>> wrote:
>>>