Subject: [OAUTH-WG] Proposed change to section 8.4. Defining New Authorization Endpoint Response Types

From: Eran Hammer-Lahav <[email-masked]>
Date: Mon, 18 Jul 2011 23:21:49 -0700

I have tried to accommodate both the use cases and concerns raised. The new text allows the registration of composite response types in which the order of the space-delimited values does not matter. However, every combination must be registered in order to avoid developers guessing what an unregistered combination might mean.

Feedback requested.

EHL

---

8.4.  Defining New Authorization Endpoint Response Types

   New response types for use with the authorization endpoint are
   defined and registered in the authorization endpoint response type
   registry following the procedure in Section 11.3.  Response type
   names MUST conform to the response-type ABNF.

     response-type  = response-name *( SP response-name )
     response-name  = 1*response-char
     response-char  = "_" / DIGIT / ALPHA

   The space character (%x20) is reserved for defining composite response types.
  Each composite response types MUST be registered, even if each of its components
   are individually registered. The order of components in a composite response type
   does not matter. The meaning of unregistered composite response types made up of
   individually registered values is undefined.

   For example, the response type "token code" is left undefined by this specification.
   However, an extension can define and register the "token code" response type.
  Once registered, the same combination cannot be registered as "code token", but
   both values can be used to make an authorization request, and refer to the same
   response type.

Also, change the definition of response_type in section 3.1.1:

   response_type
         REQUIRED.  The value MUST be one of "code" for requesting an
         authorization code as described by Section 4.1.1, "token" for
         requesting an access token (implicit grant) as described by
         Section 4.2.1, or a registered extension value as described by
         Section 8.4. A value containing one or more space characters (%x25)
         identifies a composite response type in which the order of the
         space-delimited sub-values does not matter.

---

From: Aiden Bell <[email-masked]>
Date: Tue, 19 Jul 2011 12:38:40 +0100

I think the wording is much improved here with regards implied relationships
between composite and non-composite types.

However, given this new found unambiguity, I think the use of the term
"composite response types" is misleading, as what is being described is
just a characteristics of "identifiers containing spaces". This newest 8.3
doesn't state if elements in the collection MUST also be registered.
This leads me to (correctly?) think I can register a list of elements where
the components may or may not be registered themselves.
In this case, we have a registered list of response type identifiers rather
than a list of response types registered.

I would propose the following modification, which puts the policy-ish term
of "compounding"
elements, more in the realm of registration, as the term "compounding" seems
to imply compound semantics, but the
registration part has a mechanism-not-policy approach.

   The space character (%x20) is reserved for defining a collection of
response type identifiers.

   Each collection of response type identifiers MUST be registered, even if
each of its components

   are individually registered. The order of components in a response type
identifier collection

   does not matter. The meaning of unregistered collections of response type
identifiers made up of

   For example, the response type “token code” is left undefined by this
specification.

   However, an extension can define and register the "token code" response
type identifier collection

   and its composite behavior.

   Once registered, the same combination cannot be registered as "code
token", but

   both values can be used to make an authorization request, and refer to
the same
   response type.

Apologies if this is unsuitable, i'm just looking at it as an implementor
and questioning my own assumptions,
then trying to make the text clearer. The validity of my assumptions isn't
presumed.

Thanks,
Aiden Bell

On 19 July 2011 07:21, Eran Hammer-Lahav <[email-masked]> wrote:

> I have tried to accommodate both the use cases and concerns raised. The new
> text allows the registration of composite response types in which the order
> of the space-delimited values does not matter. However, every combination
> must be registered in order to avoid developers guessing what an
> unregistered combination might mean. ****
>
> ** **
>
> Feedback requested.****
>
> ** **
>
> EHL****
>
> ** **
>
> ---****
>
> ** **
>
> 8.4.  Defining New Authorization Endpoint Response Types****
>
> ** **
>
>    New response types for use with the authorization endpoint are****
>
>    defined and registered in the authorization endpoint response type****
>
>    registry following the procedure in Section 11.3.  Response type****
>
>    names MUST conform to the response-type ABNF.****
>
> ** **
>
>      response-type  = response-name *( SP response-name )****
>
>      response-name  = 1*response-char****
>
>      response-char  = "_" / DIGIT / ALPHA****
>
> ** **
>
>    The space character (%x20) is reserved for defining composite response
> types.****
>
>   Each composite response types MUST be registered, even if each of its
> components****
>
>    are individually registered. The order of components in a composite
> response type****
>
>    does not matter. The meaning of unregistered composite response types
> made up of****
>
>    individually registered values is undefined.****
>
> ** **
>
>    For example, the response type “token code” is left undefined by this
> specification.****
>
>    However, an extension can define and register the "token code" response
> type.****
>
>   Once registered, the same combination cannot be registered as "code
> token", but****
>
>    both values can be used to make an authorization request, and refer to
> the same****
>
>    response type.****
>
> ** **
>
> Also, change the definition of response_type in section 3.1.1:****
>
> ** **
>
>    response_type****
>
>          REQUIRED.  The value MUST be one of "code" for requesting an****
>
>          authorization code as described by Section 4.1.1, "token" for****
>
>          requesting an access token (implicit grant) as described by****
>
>          Section 4.2.1, or a registered extension value as described by***
> *
>
>          Section 8.4. A value containing one or more space characters
> (%x25)****
>
>          identifies a composite response type in which the order of the***
> *
>
>          space-delimited sub-values does not matter.****
>
> ** **
>
> ** **
>
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth
>
>

-- 
------------------------------------------------------------------
Never send sensitive or private information via email unless it is
encrypted. http://www.gnupg.org

---

From: Mike Jones <[email-masked]>
Date: Tue, 19 Jul 2011 15:46:23 +0000

Thanks for making this change, Eran.  I propose that we use Aiden's text, because I agree that it removes the ambiguity that he identified.

                                                            -- Mike

From: [email-masked] [mailto:[email-masked]] On Behalf Of Aiden Bell
Sent: Tuesday, July 19, 2011 4:39 AM
To: Eran Hammer-Lahav; [email-masked]
Subject: Re: [OAUTH-WG] Proposed change to section 8.4. Defining New Authorization Endpoint Response Types

I think the wording is much improved here with regards implied relationships between composite and non-composite types.

However, given this new found unambiguity, I think the use of the term "composite response types" is misleading, as what is being described is
just a characteristics of "identifiers containing spaces". This newest 8.3 doesn't state if elements in the collection MUST also be registered.
This leads me to (correctly?) think I can register a list of elements where the components may or may not be registered themselves.
In this case, we have a registered list of response type identifiers rather than a list of response types registered.

I would propose the following modification, which puts the policy-ish term of "compounding"
elements, more in the realm of registration, as the term "compounding" seems to imply compound semantics, but the
registration part has a mechanism-not-policy approach.

   The space character (%x20) is reserved for defining a collection of response type identifiers.
   Each collection of response type identifiers MUST be registered, even if each of its components
   are individually registered. The order of components in a response type identifier collection
   does not matter. The meaning of unregistered collections of response type identifiers made up of
   individually registered values is undefined.

   However, an extension can define and register the "token code" response type identifier collection

Apologies if this is unsuitable, i'm just looking at it as an implementor and questioning my own assumptions,
then trying to make the text clearer. The validity of my assumptions isn't presumed.

Thanks,
Aiden Bell
On 19 July 2011 07:21, Eran Hammer-Lahav <[email-masked]<mailto:[email-masked]>> wrote:
I have tried to accommodate both the use cases and concerns raised. The new text allows the registration of composite response types in which the order of the space-delimited values does not matter. However, every combination must be registered in order to avoid developers guessing what an unregistered combination might mean.

Feedback requested.

EHL

---

   response_type

_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth

--
------------------------------------------------------------------
Never send sensitive or private information via email unless it is encrypted. http://www.gnupg.org

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 19 Jul 2011 09:07:12 -0700

You understood it perfectly.

Developers should focus only on the text in section 3.1.1, not 8.4 which is meant for extension authors and DE(s). Please review the proposed text for 3.1.1 and let me know if it provides you with all the information you need in order to implement the protocol.

I don't like the term collection. The meaning is very simple:

* registered response types can include spaces
* if a response type contains spaces, the order of its space-delimited values does not matter
* because order does not matter, only one order of each combination can be registered, but all can be used

There are no other implied requirements. You don't need to register the parts individually, only the combination.

EHL

From: Aiden Bell [mailto:[email-masked]]
Sent: Tuesday, July 19, 2011 4:39 AM
To: Eran Hammer-Lahav; [email-masked]
Subject: Re: [OAUTH-WG] Proposed change to section 8.4. Defining New Authorization Endpoint Response Types

Thanks,
Aiden Bell

Feedback requested.

EHL

---

   response_type

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 19 Jul 2011 09:24:27 -0700

Revised text. I changed it to focus on the implementation details.

In other words, all response types must be registered. If the type name includes spaces, it changes how the value is compared (space-delimited list of values where the order does not matter). That's it. Spaces only change how values are compared.

EHL

---

   If a response type contains one of more space characters (%x20), it is
   compared as a space-delimited list of values in which the order of values
   does not matter. Only one order of values can be registered, which covers
   all other arrangements of the same set of values.

   For example, the response type "token code" is left undefined by this specification.
   However, an extension can define and register the "token code" response type.
   Once registered, the same combination cannot be registered as "code token", but
   both values can be used to denote the same response type.

   response_type
         REQUIRED.  The value MUST be one of "code" for requesting an
         authorization code as described by Section 4.1.1, "token" for
         requesting an access token (implicit grant) as described by
         Section 4.2.1, or a registered extension value as described by
         Section 8.4. If the response type contains one or more space characters
         (%x20), it is interpreted as a space-delimited list of values, where
         the order of values does not matter (e.g. "a b" is the same as "b a").

---

From: Mike Jones <[email-masked]>
Date: Tue, 19 Jul 2011 16:33:35 +0000

Good

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Eran Hammer-Lahav
Sent: Tuesday, July 19, 2011 9:24 AM
To: OAuth WG
Subject: Re: [OAUTH-WG] Proposed change to section 8.4. Defining New Authorization Endpoint Response Types

EHL

---

   response_type

---

From: Aiden Bell <[email-masked]>
Date: Tue, 19 Jul 2011 18:08:17 +0100

This seems clearer Eran. I don't blame you for not liking "collection", I
was searching for a term without
too much theoretical background; Your revision reads much better.

I'm happy with it. This seems like a good alternative now if parsing is the
concensus.

Thanks again,
Aiden

On 19 July 2011 17:33, Mike Jones <[email-masked]> wrote:

> In other words, all response types must be registered. If the type name
> includes spaces, it changes how the value is compared (space-delimited list
> of values where the order does not matter). That's it. Spaces only change
> how values are compared.
>
> EHL
>
> ---
>
> type.

---

From: Breno <[email-masked]>
Date: Wed, 20 Jul 2011 08:21:06 -0700

> On 19 July 2011 17:33, Mike Jones <[email-masked]> wrote:
Also agree that this is a reasonable compromise.

-- 
Breno de Medeiros

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Wed, 20 Jul 2011 10:15:01 -0700

Looks like we have consensus for the new text. I'd like to ask the chairs to close issue 18 (or note it resolved until the I-D freeze is over and I can push a revised draft).

EHL

---

From: Barry Leiba <[email-masked]>
Date: Fri, 22 Jul 2011 10:08:21 -0400

> Looks like we have consensus for the new text. I'd like to ask the chairs
> to close issue 18 (or note it resolved until the I-D freeze is over and I can
> push a revised draft).

I agree; it looks like folks are happy with this text.  I'll close
this one as well.  If there's a problem in the -19 version of the
draft, we can re-open it.

Barry, as chair