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

Nat Sakimura nat at sakimura.org
Mon Oct 14 17:39:39 UTC 2013


2013/10/14 Mike Jones <Michael.Jones at microsoft.com>

>  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.
>

That's so because I have cut down them for the code flow and did not
re-incorporate other definitions while I concatenated the split version.
For incorporating them, I thought it was important to group them by the
chapters. So, the first 12 would have been under "code flow
authentication", followed by the definitions for "implicit flow", and so
on, so that if the implementer was only building the code flow
authentication server, he needs to read only that section. I could have
done it, but I did not complete.

To make it less top heavy, we might want to move some of the terms to the
specific sections.


> 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.
>

Page length concern is legitimate, but your argument does not answer the
ordering issues nor the separation of the definition and explanation text
and the source indication.

****
>
> ** **
>
> Your draft had entirely left out the hybrid flows that are retained in
> Section 2.3.
>

In fact, it was subsumed in the implicit flow. The separation was whether
the authorization endpoint response was returned in the query parameter or
the fragment. For "code token" and "code id_token" and "code token
id_token", just adding the token endpoint to the implicit flow section and
pointing it to the code flow is enough. I would drop the Hybrid flows
section as an independent section. That would cut down about 4 pages.


> 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.
>

What was rather important was that we could just point out that if you want
code flaw authentication, then you can just implement section 3. In my
version, each top level section was separate specs in essence.

IMHO,

3.<http://nat.sakimura.org/wp-content/uploads/2013/08/openid-connect-all-1_0.html#anchor7>
Authentication - Code Flow
4.<http://nat.sakimura.org/wp-content/uploads/2013/08/openid-connect-all-1_0.html#anchor11>
Authentication - Implicit Flows

is much more visually clear than

2. <http://openid.net/specs/openid-connect-core-1_0-13.html#Authentication>
Authentication
    2.1.<http://openid.net/specs/openid-connect-core-1_0-13.html#CodeFlowAuth>
Authentication using the Authorization Code Flow
    2.2.<http://openid.net/specs/openid-connect-core-1_0-13.html#ImplicitFlowAuth>
Authentication using the Implicit Flow
    2.3.<http://openid.net/specs/openid-connect-core-1_0-13.html#HybridFlowAuth>
Authentication using the Hybrid Flow


> ****
>
> ** **
>
> 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.
>

I was not talking about the toc depth but pointing out that request
parameter list being the 5 levels deep is a bit excessive. I used 2 as the
depth since that would give a better overall picture to the readers rather
than going into the details.

As to the toc itself is concerned, even with tocdepth="4", my version gives
visually clearer structure to the users, IMHO.

While I am on the structure, one of the thing I did was to group the
responses: i.e., create a section called xxxx Response and put "successful
response" and "error response" as a pair. This is IMHO cleaner again than
just talk about "response" and then have "error response" as a subsection
as it is more symmetric.

> ****
>
> ** **
>
> 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.)
>

Again, I am not talking about tocdepth. I would flatten it. The content of
the Authorization Request section is nothing but the explanation leading to
the parameters.

Also, I would put the examples after the parameters, as the examples are
non-normative explanation about the parameters use.


> ****
>
> ** **
>
> I don’t care whether we make “scope” the first parameter described or
> “response_type”.  Both are important behavioral switches.
>

IMHO, "scope" is the first switch in terms of the OpenID Connect. If the
scope does not have "openid" in it, all the other processing stops. It is
the first thing that the program checks.


> ****
>
> ** **
>
> 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.
>

ID Token is not a side effect. This is the main effect in the
authentication. Unfortunately, it has not been clear for the reader till
now.

At the very least, drop "Space delimited, case sensitive list of ASCII
OAuth 2.0 scope values." and "Other scope values MAY be present." since it
is clear from the RFC6749. Also, I would drop the reference for 4.1 etc.
here, since we are to talk only about authentication here. Anything but the
pure authentication related things has to be dropped.

So, if you do not want to talk about ID Token etc., then it would become:


scopeREQUIRED. The value MUST contain the openid.

instead of the current text:

scopeREQUIRED. 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.
Note: We are just talking about pure authentication here. Since it is a
pure authentication, we do not talk about claims. Thus, only the scope
defined in this spec here is openid. It's effect is to return ID Token. (Is
there anything else here?) That's why my text came to be:

scopeREQUIRED. 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.

I raised scope just as an example for wordiness. Other parameters like
response_type follows the same pattern. For example compare between:

response_typeREQUIRED. The value MUST be code.

and

response_typeREQUIRED. OAuth 2.0 registered response type value that
determines how the Authorization Response is returned to the Client. When
using the Authorization Code Flow, this value MUST be code.

The section is just talking about the case where the value is "code". Most
of the text here is superfluous, so we should adopt the former.

> ****
>
> ** **
>
> 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 2.1.2.4, 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 2.1.2.4?
>
I am asking to remove anything but strictly authentication related things
from the section. This section is talking about pure authentication.
Current text is too broad. It talks about "authorization" in general,
including that for the claims.In addition, a lot of text is repeated from
the earlier section. For example, text from the explanation of prompt
parameters are repeated here as well as the text from 2.1.2.3. We should
remove these. What would be left after removing the dupplicate text and
something that are not strictly authentication? My gut feeling is that we
can completely drop 2.1.2.4.


> ****
>
> ** **
>
> 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.
>
It does not have to. According to Webster:

the basic structure of something

and according to OxfordDictionaries.com:

a basic structure underlying a system, concept, or text

A framework has to allow something to be built upon and extended, but it
could be useful as is. What we have here is exactly this.

> 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.
>
I would rather have a logical structure. Your described way of building the
system is only one way of doing it.
It could be completely reverse that the implementer may build claims
request parameter and build scopes as the alias to them. (e.g., expanding
the scope values to the claims request parameters and process it: it seems
like a more logical and less duplicating way of coding.)
So, listing out the different ways of requesting claims and going into the
details about claims seems to be more appropriate.


> ****
>
> ** 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!
>
Welcome.

I will try to call in but my internet connection here during my vacation in
Taipei is not so good so I may have some difficulty there.


> ** **
>
>                                                             -- 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 "2.2.2.1.1.<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 2.1.2.4. *
>    ***
>    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. ****
>
>  Regards, ****
>
> ** **
>
> Nat****
>
> ** **
>
> 2013/10/13 Mike Jones <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.
> For more options, visit https://groups.google.com/groups/opt_out.****
>
>
>
> ****
>
> ** **
>
> --
> Nat Sakimura (=nat)****
>
> Chairman, OpenID Foundation
> http://nat.sakimura.org/
> @_nat_en****
>
> _______________________________________________
> Openid-specs-ab mailing list
> Openid-specs-ab at lists.openid.net
> http://lists.openid.net/mailman/listinfo/openid-specs-ab
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-ab/attachments/20131015/e222b38c/attachment-0001.html>


More information about the Openid-specs-ab mailing list