[Openid-specs-ab] Dynamic Client Registration

Mike Jones Michael.Jones at microsoft.com
Wed Feb 6 20:23:42 UTC 2013

You're welcome.  Thanks for doing the discussion draft.  Comments in-line in blue.

                                             -- Mike

From: Nat Sakimura [mailto:sakimura at gmail.com]
Sent: Wednesday, February 06, 2013 12:56 AM
To: Mike Jones
Cc: openid-specs-ab at lists.openid.net Group; Justin Richer
Subject: Re: [Openid-specs-ab] Dynamic Client Registration

Thanks Mike,

Comments in-line:
2013/2/6 Mike Jones <Michael.Jones at microsoft.com<mailto:Michael.Jones at microsoft.com>>
Updated versions attached that also address Brian Campbell's review comments on Registration.  The versions at http://openid.bitbucket.org/ were also updated.

                                                            -- Mike

From: Mike Jones
Sent: Tuesday, February 05, 2013 7:12 PM
To: 'Nat Sakimura'
Cc: openid-specs-ab at lists.openid.net<mailto:openid-specs-ab at lists.openid.net> Group; Justin Richer
Subject: RE: [Openid-specs-ab] Dynamic Client Registration

I've applied the parts of Nat's discussion draft that implement working group decisions to the current registration draft.  Changes applied are:

*        Tracked wording changes intended to better harmonize with the OAuth registration draft

*        Corrected version number to -15.  (Apparently it had been erroneously incremented twice - once by me, once by Nat)

  *   Fixed #746 - Deleted the operation parameter.
  *   Fixed #745 - Deleted the rotate_secret operation.
  *   Changed the Japanese client name to make it sound more natural.
  *   Added optional issued_at response value.
  *   Added client update example.
I did not apply these changes:

So these are the discussion item.

*        Moved Terminology section out of Introduction to form an independent section and added several terminology definitions - This would make the section hierarchy of registration different than all the other Connect specs


*        Added Client Read Request (GET) - No working group decision to add this operation

If the intended behavior of the "update" was in fact "replace", then having this is very useful.

I'm going to quote Tim Bray in his recent post about OAuth 2.0<https://www.tbray.org/ongoing/When/201x/2013/01/23/OAuth>:  "The Working Group clearly needed more irritating loud-voiced minimalists stridently chanting YAGNI! YAGNI! YAGNI!<http://en.wikipedia.org/wiki/You_aren't_gonna_need_it>"  I think we're running the same danger here.  If we're going to have tight, easily implementable specs, I think the bar to add something has to be higher than whether we think something could be useful.  The bar needs to be "Is this feature necessary?".  Client read clearly isn't.

*        Added Client Delete Request (DELETE) - No working group decision to add this operation

We should discuss whether we need some sort of deactivation.

YAGNI! YAGNI! YAGNI!<http://en.wikipedia.org/wiki/You_aren't_gonna_need_it> ;-)
*        Added "Self URL" - No working group decision to add this functionality
*        Added _links - No working group decision to add this functionality

>From my read, the working group intent was to have a clearly separated endpoint for the initial registration and subsequent operations.
While my proposal was achieving that in a backward compatible way[1], the current d15 does not have that. Instead, it is looking at the existence of client_id to switch the behavior.

Actually, the server is free to switch the behavior based upon the access token used.  (In fact, it probably should.)  Requiring the client_id to be present is really a cross-check that the holder of the access token actually has the client_id value too.  It's also a syntactic difference between the two operations, which can be useful if you want to branch code paths before inspecting the access token.

While this SOA like architecture is OK (and in general, that's how OAuth is), having the ability for the server to indicate the link relations url is one step closer to HATEOAS <http://en.wikipedia.org/wiki/HATEOAS> (aka REST). In my proposal, _links.self.href represents the link-relationship defined in RFC5988 <http://tools.ietf.org/html/rfc5988> and IANA Link Relations registry<http://www.iana.org/assignments/link-relations/link-relations.xml>. In addition, we probably should define a media-type for the response, such as application/json+oauth, and define how the JSON should be serialized into URL form encoding (or JSON POST etc.) in the subsequent request. That will create a uniform interface.

I don't think that we've ever espoused HATEOAS as a Connect goal per-se.  Rather, we've tried to stand for the specs being simple, minimal, easy to implement, and easy to deploy.  That's where I'm putting my efforts, anyway.

To achieve this, syntactically, we would have three ways: HAL that I used and JSON Schema. If it were JSON Schema, it would have benn
links.rel['self'][0].href instead. I found HAL-wya of being  _links.self.href  a bit easier on my eyes so I used HAL.

This goes against the "simple" and "minimal" goals, at least as I see it.  Having "self" links is pretty esoteric.

The third way is to use HTTP response header in the form of:

Link: <https://server.example.com/clients/1234>; rel="self";
 title="oauth client registration url"

Arguably, this is the best way for OAuth, which is currently completely HTTP based.
Downside is that if we start having other binding (e.g., IMAP, XMPP, etc.), then we have to fall back to HAL or other ways.

[1] by providing _links.self.href as the registration URL + "?operation=client_update"

Requiring that the registration endpoint host a different client update endpoint for every registered client is a HUGE change and adds significant complexity without a commensurate benefit.  We already have the registration_access_token values (and client_id values) to distinguish the clients.  We don't need a third way too.
*        Added Editor's Notes - We should be tracking issues in the issue tracker instead

Did you create tracker entries?

I added https://bitbucket.org/openid/connect/issue/747/registration-21-should-request-be-form for the major one.  You might want to go through the other editor's comments and add issues for those that you think still apply.
*        Cleaned up the indents - Were there were no text changes from the original version, I tried to keep the exact text from the original to facilitate diff'ing the .xml source.  Where there were changes, I tried to keep Nat's .xml formatting.

IMHO, at some point before publishing, we should clean the indent. Perhaps creating a text without any text change but only the indent  would be good.

I'm not against doing that right before we go final but while we're still editing, I'd request that people refrain from changing the formatting of a paragraph unless you're actually changing its content.  Doing so just makes it a lot harder to tell what's actually changed.  (Actually, my diff tool can be set to ignore spacing, so if you want to change the indentation of a paragraph, that's fine with me - just don't change where the line breaks occur.)

I believe that most of the indentation inconsistencies are caused by people using text editors that assume that tab characters indent by 4 spaces.  Then when displayed using standard 8-space tab spacing, some of the text is indented too far.  It would be better if we used only spaces and no tabs, but I realize that may be possible in some editors and not others.

I don't want to do the big reformat until the very end because I expect that unless everyone finds a way to stop having tab characters inserted, the indentation inconsistencies will continue.

The other inconsistency is that while text formatted like (1) below is easier to read and maintain than text formatted like (2), some of the tools used (or people doing editing) apparently prefer (2).

For what it's worth, whenever I'm changing the majority of a paragraph, I always convert it to style (1), if necessary, to improve readability.

Also, I intentionally start different sentences on different lines of the .xml, to improve diff-ability and readability of the source.  The "big reformat" would screw that up.
*        I also did not apply a big unlisted change, which had changed the semantics of Client Update from replace-all-fields to update-only-listed-fields - No working group decision to change this functionality

Actually, it was not very clear in d14 whether it was a replacement or update. It only had a non-normative (i.e., no MUST, SHOULD, etc.)  text saying "Client Update Requests replace all previous parameters set for a client_id." Were it to be a normative text, it had to state something like:

Upon the receipt of the request, the server MUST update all the registered parameters set for a client_id in the request with the received value, MUST update all the registered parameters not included in the request but with a server default with the current server default value, and MUST delete any other previously registered parameters.

http://openid.bitbucket.org/openid-connect-registration-1_0.html#ClientUpdateRequest says:  "All Client Metadata values, other than the Client ID and Registration Access Token are replaced by this operation."  I think that this is already pretty clear, but we could add the "MUST delete" language if you think it would make it clearer.

This means

(1) the client has to store all the returned value from the registration request [it is OK but we probably should state it if so.];

Not true.  The client can simply remember what values it used in the initial registration and apply diffs to those for the changes that it wants.  The client actually doesn't need the returned values at all.  (And see the thread "Fields that the server has provisioned on the client's behalf" for a discussion of the ambiguities that trying to use the returned values could cause.)

(2) the update request MUST include all the values in (1), otherwise it may change the values;

Actually, it likely only needs to include all the values in the initial registration request - not any of those returned - other than the client_id and using the registration_access_token.

(3) the update request creates new parameters if the server defaults were added between the registration and update;

Yes, that could occur.  This actually argues against trying to pass returned values (other than the client_id and registration_access_token) back in the update request.

Now, the question is, is this the intended behavior?

This question makes me think that to clear up this ambiguity, we probably want to say that the returned values, other than client_id and registration_access_token, are informational and should not be passed back to the registration endpoint in update requests.

Also, another question is that if the server changed the server default, would this affect the currently registered values? My read is "no", but just to make sure -- and we should clarify it in any case.

Servers may or may not affect currently registered clients, with there being good (usability and security) arguments for both cases.  I don't think we can dictate this one way or another.
Justin, it would be good if you applied the changes made in this version to the OAuth registration draft as well, because there were numerous bug fixes - especially in the examples.  (BTW, you can't put more than 70 characters in an <artwork> line or xml2rfc complains when producing the .txt version.)

The .xml, .unpg (unpaginated text), and .html versions are attached.

I'll send a few questions about the current text separately.

                                                            -- Mike

From: Nat Sakimura [mailto:sakimura at gmail.com]
Sent: Monday, February 04, 2013 2:03 PM
To: Mike Jones
Cc: openid-specs-ab at lists.openid.net<mailto:openid-specs-ab at lists.openid.net> Group; Justin Richer

Subject: Re: [Openid-specs-ab] Dynamic Client Registration

OK. Now I have uploaded the correct Discussion Draft 17.

HTML: http://nat.sakimura.org/wp-content/uploads/2013/02/draft-openid-connect-registration-1_0.html
diff: http://nat.sakimura.org/wp-content/uploads/2013/02/openid-connect-registration-1_0-diff-16-17.txt
XML: http://nat.sakimura.org/wp-content/uploads/2013/02/openid-connect-registration-1_0.xml
TXT (d16): http://nat.sakimura.org/wp-content/uploads/2013/02/openid-connect-registration-1_0-d16.txt
TXT (d17): http://nat.sakimura.org/wp-content/uploads/2013/02/openid-connect-registration-1_0-d17.txt


-17 discussion version
*        Moved Terminology section out of Introduction to form an independent section and added several terminology definitions
*        Deleted the operation parameter
*        Deleted the rotate_secret
*        Added Client Read Request (GET)
*        Added Client Delete Request (DELETE)
*        Added "Self URL"
*        Added _links
*        Added Editor's Notes
*        Changed the Japanese client name to make it sound more natural
*        Added issued_at
*        Added client update example (that seems to be missing many parameters that were present in the registration request example)
*        Cleand up the indents

  *   The operation parameter was removed but since the URL for the registration and other operations are different, there should be no problem in finding out what action should be taken.
  *   The URL for update etc. (Self URL) are given in _links/self/href. For servers' backward compatibility with the current implementations, it could be set like https://server.example.com/connect/register?operation=client_update so that the existing code is likely not break (if the web application framework is putting GET and POST parameters together into an object) or needs only minor change. Clients needs to read this value and store, so it is a bigger change.
Unfortunately, I will be able to join the call only very briefly due to my flight schedule.
Nat Sakimura (=nat)
Chairman, OpenID Foundation

Nat Sakimura (=nat)
Chairman, OpenID Foundation
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-ab/attachments/20130206/8aee2ab5/attachment-0001.html>

More information about the Openid-specs-ab mailing list