Subject: [OAUTH-WG] Registration: Endpoint Definition (& operation parameter)

From: Justin Richer <[email-masked]>
Date: Mon, 11 Feb 2013 16:14:33 -0500

Draft -05 of OAuth Dynamic Client Registration [1] defines three 
fundamental operations that a client can undertake: Client Registration, 
Client Update, and Secret Rotation. Each of these actions needs to be 
differentiated *somehow* by the client and server as part of the 
protocol. Draft -00 defined only the "register" operation, drafts -01 
through -04 made use of an "operation" parameter on a single endpoint, 
which brought up a long discussion on the list on whether or not that 
was an appropriate design. Draft -05 did away with the definition of the 
"operation" parameter on a single endpoint and instead opted for 
separating the base functionality into three different endpoints.

Pro:
  - Closer to RESTful semantics of having one URL for creation and 
another URL for management of an item (eg, most REST APIs use /object 
for creation and /object/object_id for manipulation)
  - The rest of OAuth (and its extensions) defines separate endpoints 
for different actions (Authorization, Token, Revocation, Introspection) 
as opposed to a single endpoint with a mode-switch parameter
  - Client doesn't have to generate a URL string for different endpoints 
by combining parameters with a base URL

Con:
  - Not quite exactly RESTful as the spec doesn't dictate the client_id 
be part of the update or rotate URL (though and implementor's note 
suggests this)
  - Client has to track different URLs for different actions
  - Server must be able to differentiate actions based on these 
different URLs.

Alternatives include using different HTTP verbs (see other thread) or 
defining an operational switch parameter, like older drafts, on a single 
endpoint URL. Another suggested alternative is to look for the presence 
of certain parameters, such as client_id or the registration access 
token, to indicate that a different operation is requested.

There's also question of whether the Secret Rotation action needs to 
have its own endpoint, or if it can be collapsed into one of the others. 
It has been suggested off-list that the secret rotation should never be 
initiated by the Client but instead the client should simply request its 
latest secret from the server through the update (or read) semantics.

  -- Justin

[1] http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-05

---

From: Mike Jones <[email-masked]>
Date: Tue, 12 Feb 2013 01:26:16 +0000

At most, there should be two endpoints - creation and management - for a client, but the protocol should be structured such that they *can* be at the same URL, if the server so chooses.  A simple way to accomplish this is to require that the client_id value be provided as an input parameter on update operations.  Then for implementations that use a single endpoint, they can distinguish "create" and "update" operations on the management endpoint by the presence or absence of the client_id value.

If you want to have separate endpoints and don't need the client_id because you have somehow encoded it into the management endpoint URL, that's fine.  It still can serve as a useful cross-check that the client (or an attacker) is requesting a change to a client that matches the bearer token used.  But including it is necessary for implementations that want to use a single registration endpoint, rather than having a proliferation of per-client endpoints.

BTW, just for the record, OAuth 2.0 uses the same endpoint for initial access token requests and requests for refreshed access tokens - with the operations being distinguished by whether a refresh_token parameter is present.  So there's a useful OAuth precedent for doing things this way.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Justin Richer
Sent: Monday, February 11, 2013 1:15 PM
To: [email-masked]
Subject: [OAUTH-WG] Registration: Endpoint Definition (& operation parameter)

Draft -05 of OAuth Dynamic Client Registration [1] defines three fundamental operations that a client can undertake: Client Registration, Client Update, and Secret Rotation. Each of these actions needs to be differentiated *somehow* by the client and server as part of the protocol. Draft -00 defined only the "register" operation, drafts -01 through -04 made use of an "operation" parameter on a single endpoint, which brought up a long discussion on the list on whether or not that was an appropriate design. Draft -05 did away with the definition of the "operation" parameter on a single endpoint and instead opted for separating the base functionality into three different endpoints.

Pro:
  - Closer to RESTful semantics of having one URL for creation and another URL for management of an item (eg, most REST APIs use /object for creation and /object/object_id for manipulation)
  - The rest of OAuth (and its extensions) defines separate endpoints for different actions (Authorization, Token, Revocation, Introspection) as opposed to a single endpoint with a mode-switch parameter
  - Client doesn't have to generate a URL string for different endpoints by combining parameters with a base URL

Con:

  -- Justin

[1] http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-05
_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Torsten Lodderstedt <[email-masked]>
Date: Tue, 12 Feb 2013 08:17:13 +0100

Hi Mike,

why do you think the protocol should allow to have two endpoints on the same URL? Even the core spec does not allow to map tokens and authorization endpoint to the same URL.

Regards,
Torsten.

---

From: Sergey Beryozkin <[email-masked]>
Date: Tue, 12 Feb 2013 11:25:06 +0000

Hi Mike,
> At most, there should be two endpoints - creation and management - for a client, but the protocol should be structured such that they *can* be at the same URL, if the server so chooses.  A simple w…
Perhaps the text can be relaxed somehow to not refer to

/register
and
/register/{client_id}

as two different endpoints ? I think it is a single endpoint from the 
implementation point of view :-).

Or may be the spec can indeed be relaxed a bit and allow for a PUT form 
payload be sent directly to /register

Cheers, Sergey

---

From: Tim Bray <[email-masked]>
Date: Tue, 12 Feb 2013 06:43:52 -0800

?! /foo and /foo/bar are obviously distinct endpoints.
On Feb 12, 2013 3:25 AM, "Sergey Beryozkin" <[email-masked]> wrote:

>> At most, there should be two endpoints - creation and management - for a
>> client, but the protocol should be structured such that they *can* be at
>> the same URL, if the server so chooses.  A simple way to accomplish this is
>> to require that the client_id value be provided as an input parameter on
>> update operations.  Then for implementations that use a single endpoint,
>> they can distinguish "create" and "update" operations on the management
>> endpoint by the presence or absence of the client_id value.
>>
>  If you want to have separate endpoints and don't need the client_id
>> because you have somehow encoded it into the management endpoint URL,
>> that's fine.  It still can serve as a useful cross-check that the client
>> (or an attacker) is requesting a change to a client that matches the bearer
>> token used.  But including it is necessary for implementations that want to
>> use a single registration endpoint, rather than having a proliferation of
>> per-client endpoints.
>>
>> BTW, just for the record, OAuth 2.0 uses the same endpoint for initial
>> access token requests and requests for refreshed access tokens - with the
>> operations being distinguished by whether a refresh_token parameter is
>> present.  So there's a useful OAuth precedent for doing things this way.
>>
>>                                 -- Mike
>>
>> From: [email-masked] [mailto:[email-masked]**] On Behalf
>> Of Justin Richer
>> differentiated *somehow* by the client and server as part of the protocol.
>> Draft -00 defined only the "register" operation, drafts -01 through -04
>> made use of an "operation" parameter on a single endpoint, which brought up
>> a long discussion on the list on whether or not that was an appropriate
>> design. Draft -05 did away with the definition of the "operation" parameter
>> on a single endpoint and instead opted for separating the base
>> functionality into three different endpoints.
>>
>> Pro:
>> another URL for management of an item (eg, most REST APIs use /object for
>> creation and /object/object_id for manipulation)
>> for different actions (Authorization, Token, Revocation, Introspection) as
>> opposed to a single endpoint with a mode-switch parameter
>> [1] http://tools.ietf.org/html/**draft-ietf-oauth-dyn-reg-05<http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-05>
>> ______________________________**_________________
>> OAuth mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/**listinfo/oauth<https://www.ietf.org/mailman/listinfo/oauth>
>> ______________________________**_________________
>> OAuth mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/**listinfo/oauth<https://www.ietf.org/mailman/listinfo/oauth>
>>
>
> ______________________________**_________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/**listinfo/oauth<https://www.ietf.org/mailman/listinfo/oauth>
>

---

From: Justin Richer <[email-masked]>
Date: Tue, 12 Feb 2013 09:57:47 -0500

Technically you could have your auth endpoint be:

/oauth?method=authorization

and your token endpoint be:

/oauth?method=token

and they're syntactically being served by the same URL. It's a 
deep-in-the-weeds argument of little value whether or not you consider 
these to be "separate endpoints" from the server perspective. You could 
also, if you so choose, define your endpoints to be the same URL and 
switch in a side-effectful fashion on parameters like response_type and 
grant_type. I think you'd be a bit nuts to do it that way, but you could 
pull it off.

The important thing is that because they're defined in the spec as 
"separate endpoints", all clients expect there to be one URL for authz 
and one for tokens, and so all clients have two slots for them. Clients 
are not expected to take one URL and add a parameter to *make* the other 
URL, they're expected to be given two URLs.

I think that's a very important difference.

  -- Justin

---

From: John Bradley <[email-masked]>
Date: Tue, 12 Feb 2013 12:00:48 -0300

It can be argued that /foo  and /foo?provider=abc  are different URI resources.

Nat and I were recommending that the registration return a update URI that can be unique per client.

In the Apps for domains or Salesforce case the hosting client could be encoded into the path or a parameter if required, or it could even be a different host name if some client's data needed to be kept in a particular jurisdiction like Canada. (honestly there are laws to prevent you hosing data in the US) 

The update URI returned may also be exactly the same as the original create URI that should be left up to the Registration server.

Allowing the Registration server to set the update URI is the most flexible for supporting multi tenant and other use-cases.  

the only downside is that the client needs to remember what it is.  As the client needs to remember a secret and the locations of the endpoint's I don't think that is a large burden.

In reality the only clients possibly having a issue with that are going to be native clients, but they are generally registered and managed by a developer and not by individual client instances.

The problem is a native client is not going to keep it's secret for updating safe.   It would work if client instances create their own unique client_id, but at that point managing another parameter is the least of your worries.

John B.

On 2013-02-12, at 11:43 AM, Tim Bray <[email-masked]> wrote:

> as two different endpoints ? I think it is a single endpoint from the implementation point of view :-).
> 
> Or may be the spec can indeed be relaxed a bit and allow for a PUT form payload be sent directly to /register
> 
> Cheers, Sergey
>

---

From: Sergey Beryozkin <[email-masked]>
Date: Tue, 12 Feb 2013 15:01:44 +0000

> ?! /foo and /foo/bar are obviously distinct endpoints.

definitely yes from the client's  point of view, at the implementation 
level - it is the internal detail, right ?

Cheers, Sergey

>
> On Feb 12, 2013 3:25 AM, "Sergey Beryozkin" <[email-masked]
> <mailto:[email-masked]>> wrote:
>
>     Hi Mike,
>         At most, there should be two endpoints - creation and management
>         - for a client, but the protocol should be structured such that
>         they *can* be at the same URL, if the server so chooses.  A
>         simple way to accomplish this is to require that the client_id
>         value be provided as an input parameter on update operations.
>           Then for implementations that use a single endpoint, they can
>         distinguish "create" and "update" operations on the management
>     Or may be the spec can indeed be relaxed a bit and allow for a PUT
>     form payload be sent directly to /register
>
>     Cheers, Sergey
>
>         If you want to have separate endpoints and don't need the
>         client_id because you have somehow encoded it into the
>         management endpoint URL, that's fine.  It still can serve as a
>         useful cross-check that the client (or an attacker) is
>         requesting a change to a client that matches the bearer token
>         used.  But including it is necessary for implementations that
>         want to use a single registration endpoint, rather than having a
>         proliferation of per-client endpoints.
>
>         BTW, just for the record, OAuth 2.0 uses the same endpoint for
>         initial access token requests and requests for refreshed access
>         tokens - with the operations being distinguished by whether a
>         refresh_token parameter is present.  So there's a useful OAuth
>         precedent for doing things this way.
>
>                                          -- Mike
>
>         From: [email-masked] <mailto:[email-masked]>
>         [mailto:[email-masked]
>         <mailto:[email-masked]>__] On Behalf Of Justin Richer
>         To: [email-masked] <mailto:[email-masked]>
>         fundamental operations that a client can undertake: Client
>         Registration, Client Update, and Secret Rotation. Each of these
>         actions needs to be differentiated *somehow* by the client and
>         server as part of the protocol. Draft -00 defined only the
>         "register" operation, drafts -01 through -04 made use of an
>         "operation" parameter on a single endpoint, which brought up a
>         long discussion on the list on whether or not that was an
>         appropriate design. Draft -05 did away with the definition of
>         the "operation" parameter on a single endpoint and instead opted
>         for separating the base functionality into three different
>         endpoints.
>
>         Pro:
>             - Closer to RESTful semantics of having one URL for creation
>         and another URL for management of an item (eg, most REST APIs
>         use /object for creation and /object/object_id for manipulation)
>             - The rest of OAuth (and its extensions) defines separate
>         endpoints for different actions (Authorization, Token,
>         Revocation, Introspection) as opposed to a single endpoint with
>         a mode-switch parameter
>             - Client doesn't have to generate a URL string for different
>         endpoints by combining parameters with a base URL
>
>         Con:
>         [1] http://tools.ietf.org/html/__draft-ietf-oauth-dyn-reg-05
>         <http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-05>
>         _________________________________________________
>         OAuth mailing list
>         [email-masked] <mailto:[email-masked]>
>         https://www.ietf.org/mailman/__listinfo/oauth
>         <https://www.ietf.org/mailman/listinfo/oauth>
>         _________________________________________________
>         OAuth mailing list
>         [email-masked] <mailto:[email-masked]>
>         https://www.ietf.org/mailman/__listinfo/oauth
>         <https://www.ietf.org/mailman/listinfo/oauth>
>
>
>     _________________________________________________
>     OAuth mailing list
>     [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: Tue, 12 Feb 2013 10:10:13 -0500

So, I think we agree in general, but to be explicit: I want a server to 
be free to include the client_id as an input parameter if it wants to, 
but I would rather not have the client be required to compose that 
parameter onto the base registration URL on its own. This is to preserve 
the flexibility on the server side to deploy things as you describe 
below, but also to have URL path components as the identifier (common in 
REST frameworks) if it so chooses. The client shouldn't ever care which 
pattern the server wants to use. This is the motivation behind providing 
the client management URL as part of the response (separate discussion).

Also, for the record, OAuth 2.0 does not use the same endpoint for 
different things in the way you describe. To refresh a token, you send a 
request to the token endpoint with grant_type=refresh_token (section 6). 
The "grant_type" parameter is explicitly designed as a mode-switch 
parameter (for instance, see the discussion in section 4.5) and the 
refresh token flow is no different. Some early drafts of the OAuth 2.0 
core document even called out refresh token as a parallel "flow" with 
the rest of them, like authorization_code and implicit, but that seemed 
to confuse people more than it helped, so Eran pulled it into a separate 
section entirely. Nevertheless, the structure and syntax remains parallel.

  -- Justin

---

From: Torsten Lodderstedt <[email-masked]>
Date: Tue, 12 Feb 2013 19:02:40 +0100

> I think that's a very important difference.

I fully agree.

---

From: Nat Sakimura <[email-masked]>
Date: Sun, 17 Feb 2013 14:55:39 +0900

+1

-- 
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en