[Openid-specs-ab] [OpenID board] OpenID Connect Specs Nearing Completion

Mike Jones Michael.Jones at microsoft.com
Mon Oct 14 08:45:15 UTC 2013

Sorry - I'm just seeing this now, as the message got sorted into a folder other than my Inbox I was working all day on issue resolutions and hadn't checked it.

Thanks for taking the time to start a detailed review Nat.  That's really important.

At a meta level, I realize that not ever structuring decision in the draft that I produced is the same as in the proof-of-concept versions you produced.  We can talk about the differences and decide what changes we do and don't want to make on the call tomorrow.  For what it's worth, often the differences are there to incorporate content that was present in Messages or Standard that had been omitted from the draft that you produced, and to try to do so with a logical structure.

The terminology section is one such case.  Your draft has only 12 term definitions.  The Core spec has 33 - all of them necessary.  I didn't adopt your convention of making giving every term a section heading because with only 12 terms, the terminology already stretched across 3 pages, whereas all 33 definitions fit onto three pages in my draft.  If we're interested countering perceptions that the specs are too long, starting out with what could be around 8 pages just for terminology seems like it would be self-defeating on our part.  I'm not adamant about this, but given how long things already were when formatted as you did, I wanted to give the working group the choice first before changing the terminology formatting and ordering.

Your draft had entirely left out the hybrid flows that are retained in Section 2.3.  Yes, Code, Implicit, and Hybrid could have been Sections 2, 3, and 4, rather than 2.1, 2.2, and 2.3, but it makes more logical sense to have one section on Authentication with three subsections describing the alternative ways to do it, than opening the document with three different top-level sections - all about the same topic.  Again, it doesn't have to stay this way, but I tried to have the document have as logical a structure as possible - even if it wasn't exactly the same as what you proposed.

Also, about section depth, to really understand your document structure, I had to rebuild it with tocdepth="4" (showing 4 levels of section structure in the table of contents), rather than 2.  People can view the resulting docs here http://self-issued.info/misc/openid-connect-all.html and here http://self-issued.info/misc/openid-connect-all.txt.  For instance, your table of contents wasn't showing any of the structure under Authorization Endpoint or Token Endpoint.

About the detail with "Authorization Request Parameters" being described in a subsection of the "Authorization Request section", that makes logical sense, but we could flatten it one level or drop the header if people are adamant about it.  (Or we could simply build with tocdepth="4" and not show it in the table of contents.  All we'd be leaving out would be the "Authorization Request Parameters" headings under "Authorization Request", which wouldn't confuse anybody.)

I don't care whether we make "scope" the first parameter described or "response_type".  Both are important behavioral switches.

I disagree with some of your proposed text for "scope".  The "openid" scope does a lot more than just request an ID Token.  It declares that the Authorization Request is an OpenID Connect Authentication Request, which brings in a lot more meaning than just requesting an ID Token.  (That's just a side effect.)  We shouldn't confuse people by letting them think that that's all the "openid" scope does.  I'll note that the sentence you introduced (starting "This scope value requests ID Token...") was in neither Messages nor Standard.

I'm fine deleting the "Space delimited, case sensitive list of ASCII OAuth 2.0 scope values." from the scope definition.

I'm not following your point about, but I can easily believe that there's still text that we want to relocate.  (For instance, the current draft -14, which you can view at http://openid.bitbucket.org/openid-connect-core-1_0.html, moved some vestigial Self-Issued text that used to be in Section 2.)  What specific changes do you want to see made to

I hate the word "framework" in your proposed title "Claims Framework" because it doesn't really convey the right meaning.  A framework is something you use as a template or structure to build something more specific, which isn't what we're doing here.  I'm open to other titles than just "Claims", however.  "Claims Mechanisms" is clunky, but would at least be correct.  I'm sure we can come up with something we all like on the call.  (BTW, if you replace, "a framework" with "mechanisms" in your introductory sentences, I think they work.)

The order of the Claims subjections are related to the likelihood of implementers actually using them.  So claims scopes, standard claims, and UserInfo come first.  Then "claims_locales".  Then the "claims" request parameter.  Then aggregated and distributed claims.  Other orders are possible, but that was my rationale.

Anyway, thanks again for starting your review.  I'm sure we'll make progress on lots of these things during the call.  Talk to you then!

                                                            -- Mike

From: openid-board-bounces at lists.openid.net [mailto:openid-board-bounces at lists.openid.net] On Behalf Of Nat Sakimura
Sent: Sunday, October 13, 2013 11:13 AM
To: openid-connect-interop at googlegroups.com
Cc: openid-specs-ab at lists.openid.net; board at openid.net
Subject: Re: [OpenID board] OpenID Connect Specs Nearing Completion

Thank you very much, Mike.
It is a great work. Having said that,

I have some comments on it.

  1.  The terminology section is not assuming the agreed upon structure as in http://nat.sakimura.org/wp-content/uploads/2013/08/openid-connect-all-1_0.html [1]. Note that the order of the terms in [1] is not alphabetical but in the semantic order: i.e., the term that is used in the text appears before it. Also, it is separating out the definition text and the notes. That is adding to the readability of the text greatly. It is also showing where it came from.
  2.  The agreed upon structure is much less deep. It was one of the main consideration in restructuring. It is adding to the ease for grasping the structure. For example, in your version, it is "<http://openid.net/specs/openid-connect-core-1_0-13.html#ImplicitRequestParameters>  Authorization Request Parameters" while in [1], it is "3.1.1.  Request Parameters".
  3.  As to the order of the request parameters are concerned, I have placed 'scope' at the top since it acts as the switch between OpenID call and pure OAuth call. This would definitely help the user when writing the code.
  4.  For the definition of 'scope', I change the text as follows to make it clear that it is stating about the value.

REQUIRED. The value MUST contain the openid. This scope value requests ID Token, which is a JWT that includes the Claims about the End-User Authentication event.

Your text is:

REQUIRED. Space delimited, case sensitive list of ASCII OAuth 2.0 scope values. OpenID Connect requests MUST contain the openid scope value. Other scope values MAY be present. See Sections 4.1<http://openid.net/specs/openid-connect-core-1_0-13.html#ScopeClaims> and 10<http://openid.net/specs/openid-connect-core-1_0-13.html#OfflineAccess> for additional scope values defined by this specification.

Here, at least "Space delimited, case sensitive ... " is superfluous since it is already defined in RFC6749. The former also describes the effect of this scope, while the later does not.
  5.  This version still has claims authorization components in
  6.  The "4. Claims" is not describing only about what is claims but also how the claims are to be requested and received. That's why [1] is using the chapter name "Claims Framework." I think this title is more appropriate, and has been agreed upon in the WG.
  7.  Accordingly, the description about this chapter should also be strengthend. Your version states:

     This section specifies how the Client can obtain Claims about the End-User and defines a
     standard set of basic profile Claims.

while [1] states:

This section defines a framework in which the client may obtain the claims about the End User. It can be done through the pre-defined scopes values or through more granular claims parameter. The claims can come from a single source or distributed sources as well.
The later, IMHO, is clearer.

  1.  Again, "4. Claims" is not assuming the order of the agreed upon structure. 4.5 should be moved before 4.2.


2013/10/13 Mike Jones <Michael.Jones at microsoft.com<mailto:Michael.Jones at microsoft.com>>
I posted this note at http://self-issued.info/?p=1137 and on Twitter as @selfissued to raise awareness that the time to do a final review of the OpenID Connect specs is now.

                                                            -- Mike

OpenID Connect Specs Nearing Completion

Based on feedback from developers, the OpenID Connect<http://openid.net/connect/> working group decided to replace the OpenID Connect Messages<http://openid.net/specs/openid-connect-messages-1_0-20.html> and OpenID Connect Standard<http://openid.net/specs/openid-connect-standard-1_0-21.html> specifications with a new OpenID Connect Core<http://openid.net/specs/openid-connect-core-1_0-13.html> specification that combines the contents from both of them before finishing OpenID Connect.  The content has also been restructured to separate Authentication from other features such as Claims and to have separate Authentication sections for the different OAuth 2.0 flows.  No changes to the protocol were made.  The publication of this new spec is another major step towards finishing OpenID Connect.

Please review this and the other OpenID Connect specifications in the coming week.  While a few local changes will still be made this week to address issues that have been identified<https://bitbucket.org/openid/connect/issues?status=new&status=open&sort=-id> since the approval of the Implementer's Drafts<http://self-issued.info/?p=1095>, I fully expect that the working group will decide at the in-person working group meeting<http://openid-wg-oct-2013.eventbrite.com/> just over a week from now that it's time to publish proposed final specifications.

Thanks to Nat Sakimura for producing a proof-of-concept document restructuring<http://nat.sakimura.org/2013/08/27/refactoring-openid-connect-drafts/> that the structure of the current OpenID Connect Core<http://openid.net/specs/openid-connect-core-1_0-13.html> spec is based upon.  And thanks to Torsten Lodderstedt for convincing us that the specs will be clearer by better separating the descriptions of logically distinct features while combining previously separate descriptions of highly interrelated functionality.

You received this message because you are subscribed to the Google Groups "OpenID Connect Interop" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openid-connect-interop+unsubscribe at googlegroups.com<mailto:openid-connect-interop%2Bunsubscribe at googlegroups.com>.
For more options, visit https://groups.google.com/groups/opt_out.

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

More information about the Openid-specs-ab mailing list