Subject: [OAUTH-WG] Refactoring Dynamic Registration

From: "Richer, Justin P." <[email-masked]>
Date: Tue, 27 Aug 2013 14:06:14 +0000

After last week's design team call, at Derek's suggestion, I took time today to refactor the Dynamic Registration draft into two pieces: "core" and "management". The former contains the definition of the Registration Endpoint and the semantics surrounding that, the latter contains the Client Configuration Endpoint as well as the "non-essential" client metadata parameters.  

I did this refactoring with an axe, so there are almost certainly bits and pieces that are in the wrong document. In particular, I've kept the use cases in the "core" document even though they reference concepts and constructs defined in the "management" spec. This way people that don't want to deal with a configuration management API can implement just the "core" registration spec and call it a day, while people who want to have full lifecycle control can do the "management" spec on top of it. This does increase the optionality by making the client configuration endpoint parameters optional, but that's the tradeoff for having things cut this way.

You can read both the specs here:

http://tools.ietf.org/html/draft-richer-oauth-dyn-reg-core-00

http://tools.ietf.org/html/draft-richer-oauth-dyn-reg-management-00

I've uploaded these as individual submissions for now. If the working group decides to move forward with this refactoring, I expect both documents to move in tandem through the RFC approval process.

 -- Justin

---

From: Anthony Nadalin <[email-masked]>
Date: Tue, 27 Aug 2013 17:20:25 +0000

Thanks for splitting this and making it simple.

It's unclear if the server must send the metadata back in same form/order/ as sent, that is, does client expect to get back only what was sent with what server values will be or can client deal with defaults that the sever sets 

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Richer, Justin P.
Sent: Tuesday, August 27, 2013 7:06 AM
To: oauth mailing list
Subject: [OAUTH-WG] Refactoring Dynamic Registration

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

---

From: Justin Richer <[email-masked]>
Date: Tue, 27 Aug 2013 14:11:49 -0400

A JSON object is not order dependent by definition, so order of elements 
doesn't matter.

In the section on client metadata and the client information response, 
it's stated that the server can:

1) Override a client's requested values and replace with its own
2) Insert a new field/value that the client didn't supply (effectively a 
server default)
3) Restrict the value of a given field

Therefore, clients MUST deal with whatever kinds of extra JSON a server 
might respond (so long as it's a valid JSON object). Thankfully, since 
this is JSON and not a schema-based XML format, this is trivial to 
implement for the client.

If you have suggestions about how to word this better, please submit text.

  -- Justin

---

From: Anthony Nadalin <[email-masked]>
Date: Tue, 27 Aug 2013 18:22:31 +0000

Understand all that  but does not say what the response will be on an additional parameter that the server does not understand,  does the parameter come back with a null, or is the parameter omitted on response ?

-----Original Message-----
From: Justin Richer [mailto:[email-masked]] 
Sent: Tuesday, August 27, 2013 11:12 AM
To: Anthony Nadalin
Cc: oauth mailing list
Subject: Re: Refactoring Dynamic Registration

A JSON object is not order dependent by definition, so order of elements doesn't matter.

In the section on client metadata and the client information response, it's stated that the server can:

1) Override a client's requested values and replace with its own
2) Insert a new field/value that the client didn't supply (effectively a server default)
3) Restrict the value of a given field

Therefore, clients MUST deal with whatever kinds of extra JSON a server might respond (so long as it's a valid JSON object). Thankfully, since this is JSON and not a schema-based XML format, this is trivial to implement for the client.

  -- Justin

On 08/27/2013 01:20 PM, Anthony Nadalin wrote:
> It's unclear if the server must send the metadata back in same 
> form/order/ as sent, that is, does client expect to get back only what 
> was sent with what server values will be or can client deal with 
> defaults that the sever sets
>

---

From: Justin Richer <[email-masked]>
Date: Tue, 27 Aug 2013 14:33:50 -0400

If the server does not understand a parameter (and by this, remember, we 
mean a field in the JSON object, not a query parameter), it can accept 
it, ignore it, replace it with a default value, or return an error.

Think of it in terms of the data model: The client has some model of 
what information it knows about, and the server's got some internal 
model of what a "registered client" is, and the client information 
response reflects the *server's* model of a client. Ultimately, the 
client is making a registration request, the server is returning the 
reality of what was actually registered. The client MUST defer to the 
server's values in these cases. If the server returns a value that the 
client doesn't know about (and doesn't know what to do with), the client 
will ignore that.

If the server's ignoring the parameter completely (which I think will be 
the common implementation), the server will just leave it out of the 
returned object entirely. That's what our server does if you send it 
some parameter that it doesn't know or care about -- it will safely 
ignore the field when it saves the object and echoes the configuration 
back. I'll here note that we didn't do anything special to make that 
happen, that's pretty much out of the box JSON library behavior in my 
experience.

The server could return a null value, or replace it with some default 
value that the server likes better. If the server's data model is 
somehow normalized and wants to take and remember *whatever* the client 
sends, it can echo back what the client sent. I don't think that's going 
to be very common in practice though, and clients need to be prepared to 
take back whatever the server dictates. Since the server is the final 
authority of what's attached to a given client ID, this is the 
appropriate model.

  -- Justin

---

From: Anthony Nadalin <[email-masked]>
Date: Tue, 27 Aug 2013 18:38:15 +0000

This is a better explanation that what is in the current document, as this will become an interop problem that the clients need to deal with and not sure how the client is going to know how to deal with all these permutations, there should be a recommended action.

-----Original Message-----
From: Justin Richer [mailto:[email-masked]] 
Sent: Tuesday, August 27, 2013 11:34 AM
To: Anthony Nadalin
Cc: oauth mailing list
Subject: Re: Refactoring Dynamic Registration

If the server does not understand a parameter (and by this, remember, we mean a field in the JSON object, not a query parameter), it can accept it, ignore it, replace it with a default value, or return an error.

Think of it in terms of the data model: The client has some model of what information it knows about, and the server's got some internal model of what a "registered client" is, and the client information response reflects the *server's* model of a client. Ultimately, the client is making a registration request, the server is returning the reality of what was actually registered. The client MUST defer to the server's values in these cases. If the server returns a value that the client doesn't know about (and doesn't know what to do with), the client will ignore that.

If the server's ignoring the parameter completely (which I think will be the common implementation), the server will just leave it out of the returned object entirely. That's what our server does if you send it some parameter that it doesn't know or care about -- it will safely ignore the field when it saves the object and echoes the configuration back. I'll here note that we didn't do anything special to make that happen, that's pretty much out of the box JSON library behavior in my experience.

The server could return a null value, or replace it with some default value that the server likes better. If the server's data model is somehow normalized and wants to take and remember *whatever* the client sends, it can echo back what the client sent. I don't think that's going to be very common in practice though, and clients need to be prepared to take back whatever the server dictates. Since the server is the final authority of what's attached to a given client ID, this is the appropriate model.

  -- Justin

On 08/27/2013 02:22 PM, Anthony Nadalin wrote:
>> form/order/ as sent, that is, does client expect to get back only 
>> what was sent with what server values will be or can client deal with

---

From: Anthony Nadalin <[email-masked]>
Date: Tue, 27 Aug 2013 18:41:14 +0000

I believe the http://tools.ietf.org/html/draft-richer-oauth-dyn-reg-management-00 is out of scope for this WG and needs to go to the APPS area since we don't deal with other OAuth management issues

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Richer, Justin P.
Sent: Tuesday, August 27, 2013 7:06 AM
To: oauth mailing list
Subject: [OAUTH-WG] Refactoring Dynamic Registration

 -- Justin

---

From: Justin Richer <[email-masked]>
Date: Tue, 27 Aug 2013 14:41:42 -0400

OK, please submit text.

  -- Justin

---

From: Justin Richer <[email-masked]>
Date: Tue, 27 Aug 2013 14:42:37 -0400

-1, I believe that the management spec is vital for interoperability and 
well within the scope of this working group, and that the management 
spec needs to move forward in tandem with the core spec.

  -- Justin

---

From: John Bradley <[email-masked]>
Date: Tue, 27 Aug 2013 14:52:07 -0400

I appreciate that is your opinion.   Lets finish splitting the document and agree on what we agree on, then the chairs and others can render a opinion on if http://tools.ietf.org/html/draft-richer-oauth-dyn-reg-management-00 is in scope for this WG.    I happen to think it is in scope, and I suspect I am not alone in that.

Right now lets focus on the core of the spec we agree on and leave the scope issue to a later knife fight.

John B.

---

From: Eve Maler <[email-masked]>
Date: Tue, 27 Aug 2013 14:12:56 -0700

Unfortunately I haven't been able to attend the design meetings, but I've continued to follow along here with interest.

I confess that the core/management split seems a little artificial to me. I can imagine a potential use case for splitting things this way -- even a client that was *statically* provisioned its credentials might still want to manage its representation at the authorization server over time. But even so, I would normally expect to see all of this considered part of the "management" bucket, with the first step allowed to happen either on-stage or off-stage. In any case, if the split satisfies some other need I'm missing, I don't want to stand in the way.

Also, I'm still a little stumped at the reluctance to allow a full set of management operations. Is this still a concern over similarity to SCIM, which also has a full set of CRUD-type operations? If so, perhaps it's worth pointing out that many (millions?) of APIs leverage the HTTP verbs in nearly identical ways to "provision" web resources. In fact, my SCIM-related slideware even says "If you've seen one RESTful CRUD API, you've seen 'em all" :), and points out that its unique value is in the *nature* of the resources being provisioned (scoped to user identity data, as noted in the SCIM API spec itself). Similarity like this is a feature of REST, not a bug.

As an aside, I'm surprised the core spec has a SHOULD around open registration. Different APIs have different business models, and the range of possibilities legitimately includes APIs that require approval workflows etc. for onboarding devs and their client apps. In fact, that's one of the exciting things about defining dynamic (machine-to-machine) client registration that can nonetheless put gates in front of client provisioning: it makes OAuth protection more easily achievable even in "circle of trust" scenarios.

Net on the important bits:
- I'm weakly in favor of a recombined core+management spec but I'm fine with the split if others find it valuable.
- I'm in favor of keeping the management functions in scope.

	Eve

>> I've uploaded these as individual submissions for now. If the working group decides to move forward with this refactoring, I expect both documents to move in tandem through the RFC approval proces…

Eve Maler                                  http://www.xmlgrrl.com/blog
+1 425 345 6756                         http://www.twitter.com/xmlgrrl

---

From: Anthony Nadalin <[email-masked]>
Date: Tue, 27 Aug 2013 21:27:46 +0000

Well, that is just one minor nit and not sure that this is the proper base to start with for the core, I was only trying to understand the intent of the specification.  There is the fundamental issue of relationship (endpoint/ API publisher and with whom the client is trying to register with and how the registration data is organized /represented as each server has to deal with all sorts of clients.

-----Original Message-----
From: Justin Richer [mailto:[email-masked]] 
Sent: Tuesday, August 27, 2013 11:42 AM
To: Anthony Nadalin
Cc: oauth mailing list
Subject: Re: Refactoring Dynamic Registration

OK, please submit text.

  -- Justin

On 08/27/2013 02:38 PM, Anthony Nadalin wrote:
>>> what was sent with what server values will be or can client deal 
>>> with defaults that the sever sets
>>>

---

From: Justin Richer <[email-masked]>
Date: Wed, 28 Aug 2013 10:56:44 -0400

Just wanted to respond to one point:

 > SHOULD around open registration

The reason behind that was to encourage wider adoption. If you don't 
have to do any out of band or manual steps to get your client 
registered, you're more likely as a developer to use it (in my view at 
least), so I'd like to see more service providers work in that mode. Of 
course, it's not a MUST and really shouldn't be a MUST, because as you 
correctly point out there are many valid mechanisms for getting access 
to the registration API. Some are more automated and robust than others. 
What we've tried to do with BlueButton+ is require open registration but 
set policy (which we can specify in our use case) around the difference 
between openly registered clients and registry-backed clients (which 
requires a manual pre-registration step to get a software assertion 
that's presented as an access token). I forsee that when we start to 
build UMA's mechanisms into BB+, we'll have another class of clients 
that have different policies as well, and while we're not quite there 
yet I think it's important to keep the user-introduction flow like this 
in mind and possible, too.

  -- Justin