Subject: [OAUTH-WG] I-D Action: draft-ietf-oauth-token-exchange-05.txt

From: [email-masked]
Date: Fri, 08 Jul 2016 03:19:03 -0700

A New Internet-Draft is available from the on-line Internet-Drafts directories.
This draft is a work item of the Web Authorization Protocol of the IETF.

        Title           : OAuth 2.0 Token Exchange: An STS for the REST of Us
        Authors         : Michael B. Jones
                          Anthony Nadalin
                          Brian Campbell
                          John Bradley
                          Chuck Mortimore
	Filename        : draft-ietf-oauth-token-exchange-05.txt
	Pages           : 30
	Date            : 2016-07-08

Abstract:
   This specification defines a protocol for a lightweight HTTP- and
   JSON- based Security Token Service (STS) by defining how to request
   and obtain security tokens from OAuth 2.0 authorization servers,
   including security tokens employing impersonation and delegation.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-ietf-oauth-token-exchange/

There's also a htmlized version available at:
https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-05

A diff from the previous version is available at:
https://www.ietf.org/rfcdiff?url2=draft-ietf-oauth-token-exchange-05

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org.

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

---

From: Brian Campbell <[email-masked]>
Date: Fri, 8 Jul 2016 10:49:45 -0600

Draft -05 of "OAuth 2.0 Token Exchange: An STS for the REST of Us" was
published earlier this morning with the following relatively small set of
changes.

   -05

   o  Defined the JWT claim "cid" to express the OAuth 2.0 client
      identifier of the client that requested the token.
   o  Defined and requested registration for "act" and "may_act" as
      Token introspection response parameters (in addition to being JWT
      claims).
   o  Loosen up the language about refresh_token in the response to
      OPTIONAL from NOT RECOMMENDED based on feedback form real world
      deployment experience.
   o  Add clarifying text about the distinction between JWT and access
      token URIs.
   o  Close out (remove) some of the Open Issues bullets that have been
      resolved.

---------- Forwarded message ----------
From: <[email-masked]>
Date: Fri, Jul 8, 2016 at 4:19 AM
Subject: [OAUTH-WG] I-D Action: draft-ietf-oauth-token-exchange-05.txt
To: [email-masked]
Cc: [email-masked]

A New Internet-Draft is available from the on-line Internet-Drafts
directories.
This draft is a work item of the Web Authorization Protocol of the IETF.

        Title           : OAuth 2.0 Token Exchange: An STS for the REST of
Us
        Authors         : Michael B. Jones
                          Anthony Nadalin
                          Brian Campbell
                          John Bradley
                          Chuck Mortimore
        Filename        : draft-ietf-oauth-token-exchange-05.txt
        Pages           : 30
        Date            : 2016-07-08

Abstract:

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

---

From: "Manger, James" <[email-masked]>
Date: Mon, 11 Jul 2016 12:13:01 +1000

> https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-05

This spec has some useful functionality, but comes across as a tad conceited.

Suggestions:

1. Drop "An STS for the REST of Us" from the title.
"STS" is not common enough to be unexpanded. The protocol isn't a poster-child for RESTful design; as the 3rd paragraph of the introduction explicitly says ("the STS protocol defined in this specification is not itself RESTful"). Hopefully it is easier for developers than the WS-* suite, but it is from some of the same companies and for some similar purposes so "for the rest of us" doesn't really ring true (though it is a cute play on words).

2. Drop "lightweight" from the abstract.
Stick to the facts: an HTTP+JWT+JSON-based STS, as an alternative to an HTTP+SOAP+XML-based STS.

3. Drop "heavyweight" and "lightweight" from the introduction.
FROM:
   Web Service clients have used WS-Trust
   [WS-Trust] as the protocol to interact with an STS for token
   exchange, however WS-Trust is a fairly heavyweight protocol, which
   uses XML, SOAP, etc.  Whereas, the trend in modern Web development
   has been towards lightweight services utilizing RESTful patterns and
   JSON.
   ... This specification defines a lightweight protocol extending OAuth 2.0
TO:
   Web Service clients have used WS-Trust
   [WS-Trust] as the protocol to interact with an STS for token
   exchange. While WS-Trust
   uses XML and SOAP, the trend in modern Web development
   has been towards RESTful patterns and
   JSON.
   ... This specification defines a protocol extending OAuth 2.0

Requiring "only an HTTP client and JSON parser" is nice for some developers over requiring an XML/SOAP parser. But to warrant the "lightweight" tag the spec need to mention major design ideas from WS-Trust that are deliberately dropped from OAuth-2.0-Token-Exchange (and will not need to be added later).

4. Do we really need to put a non-access-token (eg an id-token) in a field named "access_token", then override that with "issued_token_type":"urn:ietf:params:oauth:token-type:id_token"?

5. I'm suspect I'm far too late to the party to comment on token_type vs {subject|requested|actor|issued}_token_type, but surely we can do better than create the confusion in this spec. I think the issue is that we want to support tokens from other parties and tokens from this AS. For the former we need to indicate the syntax (eg JWT or SAML) so the AS can parse it; for the latter we need to indicate what the AS issued it for (eg access_token or refresh_token) so the AS can look it up in the correct DB.

SUGGESTION: Rename xxxx_token_type to xxxx_token_context.

   subject_token_context
      REQUIRED. An identifier of either:
      the syntax of the token (when issued from another AS) so the AS knows how to parse it;
      or the sort of token it is (when issued by this AS). See section 3.

Adjust other xxxx_token_context definitions, and section 3.

--
James Manger

---

From: Brian Campbell <[email-masked]>
Date: Fri, 15 Jul 2016 14:36:40 -0600

Thank you, James, for the review and feedback. I apologize for the slow
reply - on top of being a busy week this was a difficult one to respond to.

It's disappointing to hear that it came off as conceited. That certainly
wasn't the intent (though I suppose it rarely is).

While I think there's plenty of precedent in things calling themselves
lightweight, whether or not it's justified, and do believe this is light
enough to warrant the use of the term, I am open to dropping "heavyweight"
and "lightweight", if you think it would improve the tone of the text.

The title is something I'm less open to changes on. Honestly, I'm really
partial to it. I described it as "really really important" on slide 7 of the
IETF 93 presentation about token exchange
<https://www.ietf.org/proceedings/93/slides/slides-93-oauth-0.pdf> and
tried to brake it down humorously in a recent identity conference
presentation
<http://www.slideshare.net/briandavidcampbell/oauth-20-token-exchange-an-sts-for-the-rest-of-us/7>.
I've had numerous positive comments about it from people who appreciate the
little touch of humor. I anticipate there may be some push-back in later
stage reviews on the unexpanded acronym but I'll cross that bridge when/if
I come to it and look to find some compromise.

The "access_token" member/parameter is required per RFC 6749 so it has to
be in the response anyway and seemed like a suitable bucket for the
returned token even when the token isn't strictly an access token. What's
an alternative, putting some dummy value in "access_token" and returning
the requested token under a different name? You mention ID Tokens, which is
a potentially interesting case as there's already sort of a way to
additionally request an ID Token by using the "openid" scope. Perhaps there
should be some discussion or guidance on that? I think that might even be
helpful for something Tony has made statements about (maybe).

Generally I think that it's a little too late to be changing parameter
names like xxxx_token_type to xxxx_token_context. Unless there's
overwhelming support from others for such a change. I do think the way that
you've articulated the distinction between tokens from other parties and
tokens from this AS is useful and I'll endeavor to add and/or adjust some
text along those lines to further clarify.

On Sun, Jul 10, 2016 at 8:13 PM, Manger, James <
[email-masked]> wrote:

> "STS" is not common enough to be unexpanded. The protocol isn't a
> poster-child for RESTful design; as the 3rd paragraph of the introduction
> explicitly says ("the STS protocol defined in this specification is not
> itself RESTful"). Hopefully it is easier for developers than the WS-*
> suite, but it is from some of the same companies and for some similar
> purposes so "for the rest of us" doesn't really ring true (though it is a
> cute play on words).
>
> Requiring "only an HTTP client and JSON parser" is nice for some
> developers over requiring an XML/SOAP parser. But to warrant the
> "lightweight" tag the spec need to mention major design ideas from WS-Trust
> that are deliberately dropped from OAuth-2.0-Token-Exchange (and will not
> need to be added later).
>
>
> 4. Do we really need to put a non-access-token (eg an id-token) in a field
> named "access_token", then override that with
> "issued_token_type":"urn:ietf:params:oauth:token-type:id_token"?
>
> 5. I'm suspect I'm far too late to the party to comment on token_type vs
> {subject|requested|actor|issued}_token_type, but surely we can do better
> than create the confusion in this spec. I think the issue is that we want
> to support tokens from other parties and tokens from this AS. For the
> former we need to indicate the syntax (eg JWT or SAML) so the AS can parse
> it; for the latter we need to indicate what the AS issued it for (eg
> access_token or refresh_token) so the AS can look it up in the correct DB.
>

---

From: Sam Whited <[email-masked]>
Date: Fri, 15 Jul 2016 16:13:41 -0500

Hi all,

Longtime reader / implementer, first time poster. I wanted to comment
specifically on the question of the title:

On Fri, Jul 15, 2016 at 3:36 PM, Brian Campbell
<[email-masked]> wrote:
> IETF 93 presentation about token exchange and tried to brake it down
> humorously in a recent identity conference presentation. I've had numerous
> positive comments about it from people who appreciate the little touch of
> humor. I anticipate there may be some push-back in later stage reviews on
> the unexpanded acronym but I'll cross that bridge when/if I come to it and
> look to find some compromise.

While I too appreciate the little touch of humor, the point the RFC
process is not humor, the point is to make something that conveys
information in an accessible and unambiguous way. I did not know the
acronym "STS" when I first glanced at this title, and even if I did
know the acronym I'm not sure that the title would immediately convey
what the document was about in its current form. This will be
detrimental to the accessibility of the document if non-expert users
have to go perform an internet search for an acronym before they've
even begun to read the document.

RFCs are generally a bit dry and sprucing them up with a bit can be
tempting. I appreciate that the joke is clever — but the less of our
own quirky and fun personalities we put into RFCs the better it will
be for the series and the clearer they will be for the developers who
will have to implement them.

Thanks,
Sam

-- 
Sam Whited
pub 4096R/54083AE104EA7AD3

---

From: Phil Hunt <[email-masked]>
Date: Fri, 15 Jul 2016 14:56:07 -0700

I agree. The title was useful as a working title as it conveyed a lot of useful intent information to members of the WG familiar with the technology.

I don’t think the broader community understands OASIS and the broader realm nor should they care.

At minimum it suggests they need to go read about STS’s before implementing the draft - which should not be needed.

Phil

@independentid
www.independentid.com <http://www.independentid.com/>[email-masked] <mailto:[email-masked]>

> On Jul 15, 2016, at 2:13 PM, Sam Whited <[email-masked]> wrote:
> 
> Hi all,
>

---

From: Brian Campbell <[email-masked]>
Date: Sat, 16 Jul 2016 08:42:53 -0600

Et tu, Phil?

Do Sam and Phil represent the general consensus here or a vocal minority?

On Fri, Jul 15, 2016 at 3:56 PM, Phil Hunt <[email-masked]> wrote:

> I agree. The title was useful as a working title as it conveyed a lot of
> useful intent information to members of the WG familiar with the technology.
>
> At minimum it suggests they need to go read about STS’s before
> implementing the draft - which should not be needed.
>
> Phil
>
> @independentid
> www.independentid.com
> [email-masked]
>
>
>
>
>

---

From: Justin Richer <[email-masked]>
Date: Sun, 17 Jul 2016 07:44:27 -0400

I, for one, appreciate the title. It's a token swap, fulfilling and in 
some ways replacing the complicated functionality of an old-school STS, 
but in a more REST-friendly fashion. OAuth is not RESTful, nor has it 
ever intended to be so. It's REST-friendly and that's a good thing.

Besides: it's a subtitle, not the root document title. I say we keep it.

  -- Justin

On 7/16/2016 10:42 AM, Brian Campbell wrote:
> On Fri, Jul 15, 2016 at 3:56 PM, Phil Hunt <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     I agree. The title was useful as a working title as it conveyed a
>     lot of useful intent information to members of the WG familiar
>     with the technology.
>
>     www.independentid.com <http://www.independentid.com>
>     [email-masked] <mailto:[email-masked]>
>
>
>
>
>
>>     On Jul 15, 2016, at 2:13 PM, Sam Whited <[email-masked]
>>     <mailto:[email-masked]>> wrote:
>>
>>     Hi all,
>>
>>     <[email-masked] <mailto:[email-masked]>>
>>     wrote:
>>     [email-masked] <mailto:[email-masked]>

---

From: Mike Jones <[email-masked]>
Date: Sun, 17 Jul 2016 14:23:52 +0000

Since you’re asking…

I must admit, every time I see the title, I cringe.  I held my nose at the time of the merge since I knew that it was important to you, but since others are raising the issue, I’ll say that I actually find it to be embarrassing.

I think we’re better off with a straightforward title without the extra clause that is both misleading and too cute by half.

                                                       Honestly,
                                                       -- Mike

From: OAuth [mailto:[email-masked]] On Behalf Of Brian Campbell
Sent: Saturday, July 16, 2016 4:43 PM
To: Phil Hunt <[email-masked]>
Cc: [email-masked]
Subject: Re: [OAUTH-WG] I-D Action: draft-ietf-oauth-token-exchange-05.txt

Et tu, Phil?

On Fri, Jul 15, 2016 at 3:56 PM, Phil Hunt <[email-masked]<mailto:[email-masked]>> wrote:
I agree. The title was useful as a working title as it conveyed a lot of useful intent information to members of the WG familiar with the technology.

Phil

@independentid
www.independentid.com<http://www.independentid.com>
[email-masked]<mailto:[email-masked]>

On Jul 15, 2016, at 2:13 PM, Sam Whited <[email-masked]<mailto:[email-masked]>> wrote:

Hi all,

On Fri, Jul 15, 2016 at 3:36 PM, Brian Campbell
<[email-masked]<mailto:[email-masked]>> wrote:

Thanks,
Sam

--
Sam Whited
pub 4096R/54083AE104EA7AD3
_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth