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

Mike Jones Michael.Jones at microsoft.com
Mon Oct 14 18:22:27 UTC 2013

I agree with John.  "code id_token" is not implicit.

Pure Implicit flows don't use the Token Endpoint.  The hybrid flows do (returning content both from the authorization endpoint and the token endpoint).

Compare the structure of 2.2 (Implicit) and 2.3 (Hybrid).  They're pretty different - exactly because the hybrid flows use both endpoints.

I think we'd be doing a disservice to implementers to try to cram them together again.  At that point, we might as well just have one "Messages" section, like we had before.

                                                                -- Mike

From: John Bradley [mailto:ve7jtb at ve7jtb.com]
Sent: Monday, October 14, 2013 10:59 AM
To: Nat Sakimura
Cc: Mike Jones; openid-specs-ab at lists.openid.net
Subject: Re: [Openid-specs-ab] [OpenID board] OpenID Connect Specs Nearing Completion

We have some terminology problems inherited from OAuth.

I don't think code+id_token is implicit.   Implicit refers to a grant being implicit in the access token returned.  It just happens to be that the example of that is fragment encoding in the spec, however using postmessage it would still be implicit.

code+id_token is by that definition not implicit while code+token is both implicit and explicit hybrid.

If you are making two categories then we have query parameter encoded response and everything else which is fragment encoded to prevent referrer_uri leaking information it should not.
As a observation the code flow to a public client is also problematic as there is a possibility that a leaking referrer may reveal code to an attacker before the real client has a chance to use it.


On 2013-10-14, at 2:39 PM, Nat Sakimura <nat at sakimura.org<mailto:nat at sakimura.org>> wrote:

2013/10/14 Mike Jones <Michael.Jones at microsoft.com<mailto: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.


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:

REQUIRED. The value MUST contain the openid.

instead of the current text:

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.

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:

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.

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

REQUIRED. The value MUST be code.


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

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<http://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!

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> [mailto: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<mailto:openid-connect-interop at googlegroups.com>
Cc: openid-specs-ab at lists.openid.net<mailto:openid-specs-ab at lists.openid.net>; board at openid.net<mailto: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

Openid-specs-ab mailing list
Openid-specs-ab at lists.openid.net<mailto:Openid-specs-ab at lists.openid.net>

Openid-specs-ab mailing list
Openid-specs-ab at lists.openid.net<mailto:Openid-specs-ab at lists.openid.net>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-ab/attachments/20131014/d00a6586/attachment-0001.html>

More information about the Openid-specs-ab mailing list