Subject: [OAUTH-WG] I-D Action: draft-ietf-oauth-dyn-reg-05.txt

From: [email-masked]
Date: Wed, 06 Feb 2013 12:15:34 -0800

A New Internet-Draft is available from the on-line Internet-Drafts directories.
 This draft is a work item of the Web Authorization Protocol Working Group of the IETF.

	Title           : OAuth Dynamic Client Registration Protocol
	Author(s)       : Justin Richer
                          John Bradley
                          Michael B. Jones
                          Maciej Machulak
	Filename        : draft-ietf-oauth-dyn-reg-05.txt
	Pages           : 21
	Date            : 2013-02-06

Abstract:
   This specification defines an endpoint and protocol for dynamic
   registration of OAuth Clients at an Authorization Server.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-ietf-oauth-dyn-reg

There's also a htmlized version available at:
http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg-05

A diff from the previous version is available at:
http://www.ietf.org/rfcdiff?url2=draft-ietf-oauth-dyn-reg-05

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

---

From: Justin Richer <[email-masked]>
Date: Wed, 6 Feb 2013 15:34:59 -0500

Thanks to all of the discussion over the last few weeks and some key 
input from Nat Sakimura, Eve Maler, and others, I've put out a revision 
of the DynReg specification that is a major change from recent 
revisions, but actually brings it back closer to the original -01 draft. 
The "operation" parameter is now gone and there are instead several 
logical endpoints for different kinds of operations. These endpoints are 
communicated to the client through a well-defined link structure.

It basically works like this:

1. client shows up at the Client Registration Endpoint, posts a JSON 
object with a few bits of metadata about itself (and potentially 
presents an Access Token that it got from some out of band process that 
acts as a "class registration" or "developer key", important to several 
known real-world use cases)

2. client gets back a JSON object filled with whatever metadata the 
server has about it, including a newly-minted client_id and (possibly) 
client_secret. The client also gets back a registration access token and 
a fully qualified URL that points to the "update endpoint". This url can 
take any form (the server can't count on the client being able to 
generate it from parts), but it's recommended that it follow a 
REST-style URL template of the form 
"https://server/registration_base_url/client_id".

3. client sends updates to this update URL, authenticated by the 
registration access token, by PUTting a JSON object with all of its 
parameters. Any fields the client leaves off the JSON object, the server 
leaves alone. Anything with a "null" value, the server deletes the 
value. The server remains free to override *any* field the client 
requests setting a particular value for. The client is not allowed to 
request a particular value for the client_secret or 
registration_access_token, for obvious reasons -- but see part 7 below.

4. The server responds back with the current state of the client as a 
JSON object, including any fields the server has provisioned on the 
client's behalf (defaults, for instance). Any fields the server has 
overridden, it currently MUST respond with. So if the client asks for 
"scope: A B C" and the server can only give it "scope: A B", then the 
server has to tell that to the client by including the field "scope: A 
B" in its response.

5. client can send an HTTP GET to the update URL to get its current 
state as a JSON object as in 4.

6. client can send an HTTP DELETE to the update URL to deprovision itself.

7. there's also a parallel endpoint for rotating the registration access 
token and client secret, since these are both security values that are 
provisioned by the server. There is some open debate of whether the 
client actually needs to be able to trigger this operation, or if the 
server should just do this as part of normal update/get requests to the 
update endpoint.

It's a major functionality change on the wire, and there's still sawdust 
on the spec language. By going with a JSON-based data model and a 
RESTful update protocol, we're getting away from core OAuth patterns, 
but I think that ultimately this can be a good thing. There have been a 
few proposals that would go somewhere between what OAuth does on other 
endpoints and what a real RESTful system would do, but I didn't see much 
purpose in going half way when the results would end up *more* complicated.

I request that everyone read it over to see if this will work for their 
use cases. The idea here remains that application protocols like OIDC 
and UMA would use this mechanism as-is with nearly all customizations in 
the client metadata table.

I hope that this all actually makes sense...

  -- Justin

On 02/06/2013 03:15 PM, [email-masked] wrote:
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Mike Jones <[email-masked]>
Date: Thu, 7 Feb 2013 02:09:55 +0000

Hi Justin,

Thanks for working to make progress on the OAuth Registration draft.  Reading through the changes, it seems to me that a number of changes were made that there wasn't yet working consensus for - in fact, some of which I don't recall being discussed by the working group at all.  These changes include:

  - Splitting the registration endpoint into multiple endpoints
  - Changing from form-encoded to JSON registration representation
  - Adding Get and Delete operations
  - Adding the Self URI concept and representation

My point is separate from whether some of those changes might be good ideas.  (Some may be.)  I would hope that in the future, before changes are made to working group drafts, that sufficient time will be first be given to the working group to adequately discuss them and come to agreement on them.

				Thank you,
				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Justin Richer
Sent: Wednesday, February 06, 2013 12:35 PM
To: [email-masked]
Subject: Re: [OAUTH-WG] I-D Action: draft-ietf-oauth-dyn-reg-05.txt

Thanks to all of the discussion over the last few weeks and some key input from Nat Sakimura, Eve Maler, and others, I've put out a revision of the DynReg specification that is a major change from recent revisions, but actually brings it back closer to the original -01 draft. 
The "operation" parameter is now gone and there are instead several logical endpoints for different kinds of operations. These endpoints are communicated to the client through a well-defined link structure.

1. client shows up at the Client Registration Endpoint, posts a JSON object with a few bits of metadata about itself (and potentially presents an Access Token that it got from some out of band process that acts as a "class registration" or "developer key", important to several known real-world use cases)

2. client gets back a JSON object filled with whatever metadata the server has about it, including a newly-minted client_id and (possibly) client_secret. The client also gets back a registration access token and a fully qualified URL that points to the "update endpoint". This url can take any form (the server can't count on the client being able to generate it from parts), but it's recommended that it follow a REST-style URL template of the form "https://server/registration_base_url/client_id".

3. client sends updates to this update URL, authenticated by the registration access token, by PUTting a JSON object with all of its parameters. Any fields the client leaves off the JSON object, the server leaves alone. Anything with a "null" value, the server deletes the value. The server remains free to override *any* field the client requests setting a particular value for. The client is not allowed to request a particular value for the client_secret or registration_access_token, for obvious reasons -- but see part 7 below.

4. The server responds back with the current state of the client as a JSON object, including any fields the server has provisioned on the client's behalf (defaults, for instance). Any fields the server has overridden, it currently MUST respond with. So if the client asks for
"scope: A B C" and the server can only give it "scope: A B", then the server has to tell that to the client by including the field "scope: A B" in its response.

5. client can send an HTTP GET to the update URL to get its current state as a JSON object as in 4.

7. there's also a parallel endpoint for rotating the registration access token and client secret, since these are both security values that are provisioned by the server. There is some open debate of whether the client actually needs to be able to trigger this operation, or if the server should just do this as part of normal update/get requests to the update endpoint.

It's a major functionality change on the wire, and there's still sawdust on the spec language. By going with a JSON-based data model and a RESTful update protocol, we're getting away from core OAuth patterns, but I think that ultimately this can be a good thing. There have been a few proposals that would go somewhere between what OAuth does on other endpoints and what a real RESTful system would do, but I didn't see much purpose in going half way when the results would end up *more* complicated.

I request that everyone read it over to see if this will work for their use cases. The idea here remains that application protocols like OIDC and UMA would use this mechanism as-is with nearly all customizations in the client metadata table.

  -- Justin

---

From: Justin Richer <[email-masked]>
Date: Thu, 7 Feb 2013 09:58:57 -0500

Mike,

Thanks for reviewing the latest draft.

First, it's my understanding that the role of the editor is not merely 
to express the gestalt of the working group (though that's a very 
important part of it) but also to drive that discussion to it's best 
technical end. I put this revision together because it's easier to 
discuss things when there's actual text on the table. If it's just a 
suggested idea, I find that people tend to get very scared of imagined 
horrors that have little to do with the actual proposals. There's an air 
of "if we do something it's going to be the worst thing" that hang 
around as long as parts are still unknown.

So I took a step out on a limb and got things down on paper. I told 
people that I was going to do this the other day. [1] Since it's easy to 
roll back any changes that the working group doesn't want, and revisions 
are cheap, I'm not afraid to pull out things that make the WG cringe. 
But at least now we have something real, and not imagined, to cringe at.

That said, there have been several discussions about the changes that 
went into this revision. The original UMA draft from which this grew was 
much JSON based, though it didn't define actions beyond the initial 
registration. From the time I took over and moved it to form-based 
actions inspired by the OIDC registration draft, I've had people asking 
me why the registration endpoint wasn't a RESTful API: why didn't it use 
HTTP verbs, why wasn't it JSON-in/JSON-out, etc. My argument at the time 
was that OAuth wasn't RESTful (because it isn't), and that the 
parallelism with the rest of OAuth would be good for DynReg. But several 
people argued, several times now, that registration could be a really 
good place to do something different without breaking the expectations 
and flavor of the rest of the OAuth framework. I still hold that's it's 
*different*, but after I saw Nat's elegant rewrite of the OIDC 
registration spec [2], I was convinced that this could actually work in 
a reasonable, non-hackish manner.

And so I decided, as editor, to take the many discussions about this 
along with the best ideas and practices that I was aware of and put them 
into a document that we could discuss and use.

I welcome discussion on the document on its merits, and not the actions 
of its editor.

  -- Justin

[1] http://www.ietf.org/mail-archive/web/oauth/current/msg10690.html
[2] 
http://nat.sakimura.org/wp-content/uploads/2013/02/draft-openid-connect-registration-1_0.html

---

From: Hannes Tschofenig <[email-masked]>
Date: Mon, 11 Feb 2013 19:28:53 +0200

Hi Justin, 

just one comment on this specific issue: 

> 1. client shows up at the Client Registration Endpoint, posts a JSON object with a few bits of metadata about itself (and potentially presents an Access Token that it got from some out of band proc…

The starting point of the dynamic registry document was that the client does not yet have some secret with the authorization server and for that reason it does all this dance. 
Now, you write that it may have some "developer key" (which is sort of similar to what the client id/client secret is). 

That cannot be right. 

Ciao
Hannes

---

From: John Bradley <[email-masked]>
Date: Mon, 11 Feb 2013 14:40:03 -0300

The client may have a developer key which is a bearer token.   How it gets it is out of scope,  however we do see in the real world developer portals where developers establish accounts and get keys/tokens for creating clients.

Depending on the IdP this master token could be issued to a native app and then used to create separate client IDs for each instance.

The spec allows a client to have a token for registering or arrive without it.    Like OAuth punted on how the client gets a ID and secret, we are punting on how the developer gets its initial token if it is required.

There are real use cases for this in API management.   It would be nice if those systems could leverage this spec rather than being forced to create something different.

John B.