OAuth 2.0 Token Exchange
draft-ietf-oauth-token-exchange-19

[Ballot comment]
A few nits:

** Section 2 and 4.  Reference the figure numbers in the text  when introducing an example.

** Figure 6.  Invalid JSON.  line ‘"sub":"https://service77.example.com”, ‘ should not end with a comma

[Ballot comment]
I have comments below, a couple of which might have been DISCUSS except that there have been enough eyes on this and enough DISCUSSes already, and I trust the authors and responsible AD to do the right thing.  So I’ve divided the comments between “higher importance” and “purely editorial”.

Of higher importance:

— Section 1.1 —
Given the extensive discussion of impersonation here, what strikes me as missing is pointing out that impersonation here is still controlled, that “A is B” but only to the extent that’s allowed by the token.  First, it might be limited by number of instances (one transaction only), by time of day (only for 10 minutes), and by scope (in regard to B’s address book, but not B’s email).  Second, there is accountability: audit information still shows that the token authorized acting as B.  Is that not worth clarifying?

— Section 8.2 —
RFC 8174 needs to be normative, along with 2119.

— Section 2.2.2 —

  If the authorization server is unwilling or unable to issue a token
  for all the target services indicated by the "resource" or "audience"
  parameters, the "invalid_target" error code SHOULD be used in the
  error response.

I always trip when I read “all” in a context like this.  I think you mean “any”, because you have “a token”.  You could arguably make it “tokens” and leave “all”, but I think changing to “any” is clearer:

NEW
  If the authorization server is unwilling or unable to issue a token
  for any target service indicated by the "resource" or "audience"
  parameters, the "invalid_target" error code SHOULD be used in the
  error response and no tokens are returned.
END

The danger with “all” is having a reader interpret the error as only occurring when the server fails *all* services, and thinking that failing one out of three still constitutes success.  I have seen this be an issue often (not with OAuth, but in general).  If you want to be absolutely clear you could even add to the end, “A request is successful only when all requested tokens are issued.”

— Section 5 —

  In addition, both delegation and impersonation introduce unique
  security issues.  Any time one principal is delegated the rights of
  another principal, the potential for abuse is a concern.  The use of
  the "scope" claim is suggested to mitigate potential for such abuse,
  as it restricts the contexts in which the delegated rights can be
  exercised.

I’m ambivalent here: is it worth also mentioning limiting the time a token is valid and possibly make it a one-time-use token?  Or is it that that’s adequately covered in the other references and shouldn’t be repeated here?

Also, is it worth referring (not copying) here to the advice in section 2.1 about the importance of authentication?

— Section 6 —
Should “TLS” here have a citation and normative reference?

=====

Purely editorial:

— Section 1 —

  An OAuth resource server, for example, might assume
  the role of the client during token exchange in order to trade an
  access token, which it received in a protected resource request, for
  a new token that is appropriate to include in a call to a backend
  service.

A suggestion: I think this would work better using a restrictive clause, rather than a non-restrictive one.

NEW
  An OAuth resource server, for example, might assume
  the role of the client during token exchange in order to trade an
  access token that it received in a protected resource request for
  a new token that is appropriate to include in a call to a backend
  service.
END

  The scope of this specification is limited to the definition of a
  basic request and response protocol for an STS-style token exchange

There should be hyphens in “request-and-reaponse protocol” (compound modifier).

— Sections 4.1 and 4.4 —

Section 4.1 says this:
  Consequently, non-
  identity claims (e.g., "exp", "nbf", and "aud") are not meaningful
  when used within an "act" claim, and therefore must not be used.

Section 4.4 says this:
  Consequently,
  claims such as "exp", "nbf", and "aud" are not meaningful when used
  within a "may_act" claim, and therefore should not be used.

I agree that neither of these should be BCP 14 key words, but I still think that being consistent is important, and I urge you to make them the same: both “must not be used” or both “should not be used” (or perhaps both “are not used”).

(I did not review the appendices.)

[Ballot comment]
(Incomplete Ballot)

A few nits:

** Section 2 and 4.  Reference the figure numbers in the text  when introducing an example.

** Figure 6.  Invalid JSON.  line ‘"sub":"https://service77.example.com”, ‘ should not end with a comma

[Ballot comment]
I'm balloting Yes; this document is solid and well-written.  I do have a
few additional (largely editorial) suggestions and a question or two,
though.

Section 2.1

  The client makes a token exchange request to the token endpoint with
  an extension grant type using the HTTP "POST" method and including
  the following parameters using the "application/x-www-form-
  urlencoded" format with a character encoding of UTF-8 in the HTTP
  request entity-body as described in Appendix B of RFC6749 [RFC6749].

This is a really long sentence.  I see how it got that way, and the RFC
Editor staff will probably have some thoughts on how to reword it, but
if you happen to have thoughts as well, feel free to have at it.

Section 2.2.1

  expires_in
      RECOMMENDED.  The validity lifetime, in seconds, of the token
      issued by the authorization server.  Oftentimes the client will
      not have the inclination or capability to inspect the content of
      the token and this parameter provides a consistent and token type
      agnostic indication of how long the token can be expected to be
      valid.  For example, the value 1800 denotes that the token will

nit: hyphenate "token-type-agnostic".

Section 4.4

Refresh my memory: did we already have a discussion about may_act as an
object vs. an array of objects?

Section 5

I'd consider also mentioning/linking the OAuth 2.0 security
considerations -- the fact that the STS is colocated with the token
endpoint takes care of ensuring a lot of its security properties.

Section 7

It's common (but not required, since it will not be relevant upon
publication as an RFC) to note that the indicated values are reflected
in early allocations from the indicated IANA registries.  In this case
I'd say "don't bother"...

Appendix B

Uh-oh, now we are up to five security ADs that have been around for this
document...

[Ballot discuss]
[early allocations have been approved]

why do we allow both client authentication (i.e., using an
actor token) and a distinct actor_token request parameter?  Is it
supposed to be the case that the actor_token parameter is only supplied
for delegation flows?  If so, that needs to be made explicit in the
document.
[suggested text forthcoming]

Are the privacy considerations (e.g., risk of a tailed per-request
error_uri) relating to the use of error_uri discussed in some other
document that we can refer to from this document's security
considerations?  (I say a bit more about this in my COMMENT.)
[better in oauth-security-topics; an external reference from this
document may or may not be appropriate]

[STS will be able to look up based on audience name what type/policy to use]

[Ballot discuss]
It looks like allocations in the OAuth URIs registry are merely
"Specification Required", so we should not have the expectation of WG
exclusivity and thus are squatting on unallocated values here.
Process-wise, that's not great and the IESG shouldn't approve a document
that is squatting on codepoints.

why do we allow both client authentication (i.e., using an
actor token) and a distinct actor_token request parameter?  Is it
supposed to be the case that the actor_token parameter is only supplied
for delegation flows?  If so, that needs to be made explicit in the
document.

Are the privacy considerations (e.g., risk of a tailed per-request
error_uri) relating to the use of error_uri discussed in some other
document that we can refer to from this document's security
considerations?  (I say a bit more about this in my COMMENT.)

Section 2.1 has:
  audience
      OPTIONAL.  The logical name of the target service where the client
      intends to use the requested security token.  This serves a
      purpose similar to the "resource" parameter, but with the client
      providing a logical name rather than a location.  Interpretation
      of the name requires that the value be something that both the
      client and the authorization server understand.  An OAuth client
      identifier, a SAML entity identifier [OASIS.saml-core-2.0-os], an
      OpenID Connect Issuer Identifier [OpenID.Core], or a URI are
      examples of things that might be used as "audience" parameter
      values.  [...]

How does the STS know what type of identifier it is supposed
to interpret the provided audience value as?

[Ballot comment]
The document could perhaps benefit from greater clarity as to whether
"security token"s refer to inputs, outputs, or both, of the token
endpoint (for the interactions defined in this specification).

Section 1

                                                            The OAuth
  2.0 Authorization Framework [RFC6749] and OAuth 2.0 Bearer Tokens
  [RFC6750] have emerged as popular standards for authorizing third-
  party applications access to HTTP and RESTful resources.  [...]

nit: possessive "applications'"

Section 1.1

This section really jumps in quickly with no lead-in to why we would
care or transition from the introduction.  I suggest:

  One common use case for an STS (as alluded to in the previous section)
  is to allow a resource server A to make calls to a backend service C on
  behalf of the requesting user B.  Depending on the local site policy and
  authorization infrastructure, it may be desireable for A to use its own
  credentials to access C along with an annotation of some form that A is
  acting on behalf of B ("delegation"), or for A to be granted a limited access
  credential to C but that continues to identify B as the authorized
  entity ("imperesonation").  Delegation and impersonation can be useful
  concepts in other scenarios involving multiple participants as well.

Section 2.1

                                                  For example, [RFC7523]
  defines client authentication using JSON Web Tokens (JWTs) [JWT].

Please clarify that these are still bearer tokens.

  The supported methods of client authentication and whether or not to
  allow unauthenticated or unidentified clients are deployment
  decisions that are at the discretion of the authorization server.

It seems appropriate to note that omitting client authentication allows
for a compromised token to be leveraged via an STS into other tokens by
anyone possessing the compromised token, and thus that client
authentication allows for additional authorization checks as to which
entities are permitted to impersonate or receive delegations from other
entities.

  The client makes a token exchange request to the token endpoint with
  an extension grant type by including the following parameters using
  the "application/x-www-form-urlencoded" format with a character
  encoding of UTF-8 in the HTTP request entity-body:

Is there more to say than "just use UTF-8"; any normalization or
canonicalization issues to consider?

  subject_token
      REQUIRED.  A security token that represents the identity of the
      party on behalf of whom the request is being made.  Typically, the
      subject of this token will be the subject of the security token
      issued in response to this request.
 
nit: I think there's a subtle grammar mismatch here, where we start off
by talking about a/the request and end up with "this request".

  In processing the request, the authorization sever MUST validate the
  subject token as appropriate for the indicated token type and, if the
  actor token is present, also validate it according to its token type.
 
I misread this the first time around; I'd suggest something like
"perform the appropriate validation procedures for the indicated token
type" (as opposed to just verifying that the presented token is a
syntactically valid instance of the claimed type).
 
  In the absence of one-time-use or other semantics specific to the
  token type, the act of performing a token exchange has no impact on
  the validity of the subject token or actor token.  Furthermore, the
  validity of the subject token or actor token have no impact on the
  validity of the issued token after the exchange has occurred.

Do we really want this strong of a statement?  I suspect that in many
environments propagating, e.g., expiration time to the exchanged
credential may be desired.

Section 2.2.1

  token_type
[...]
      contents of the token itself.  Note that the meaning of this
      parameter is different from the meaning of the "issued_token_type"
      parameter, which declares the representation of the issued
      security token; the term "token type" is typically used with this
      meaning, as it is in all "*_token_type" parameters in this
      specification. [...]

Please disambiguate what "typically used with this meaning" means.
Perhaps it would be even more clear to change this field's name to
"token_access_token_type" to match the name of the registry?

Section 2.3

  The following example demonstrates a hypothetical token exchange in
  which an OAuth resource server assumes the role of the client during
  token exchange in order to trade an access token that it received in
  a protected resource request for a token that it will use to call to
  a backend service (extra line breaks and indentation in the examples
  are for display purposes only).

We could maybe add some commas or parentheses to help the reader group
the various clauses properly.  E.g., it is "(trade an access token (that
it received in a protected resource request)) for a token...", not
"trace an access token that it received (in a protected resource request
for a token)", where parentheses indicate logical grouping.

    grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
    &resource=https%3A%2F%2Fbackend.example.com%2Fapi%20
    &subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC
    &subject_token_type=
    urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token

                    Figure 2: Token Exchange Request
Is there really supposed to be a %20 in the resource query parameter's
value?

The token octets in Figures 3 and 4 do not match up, despite the prose
indicating that they are the same token.

Section 3

Would it be appropriate to note (here or elsewhere) that for non-JWT
token formats that are a binary format, the URI used for conveying them
needs to be associated with the semantics of base64 (or otherwise)
encoding them for usage with OAuth?

                                                Token Exchange can work
  with both tokens issued by other parties and tokens from the given
  authorization server.  [...]

Does "work with" mean "accept as input" or "produce as output" or both?
For input, as both subject_token and actor_token?

  The following token type identifiers are defined by this
  specification.  Other URIs MAY be used to indicate other token types.
I'd also link to the registry here.

Why is the text about "urn:ietf:params:oauth:token-type:jwt" formatted
differently than the other URIs listed?

Section 4.1

Do we want to consider a more self-describing subject identifier scheme,
akin to
https://tools.ietf.org/html/draft-ietf-secevent-subject-identifiers ?

The example in Figure 5 appears to be using the "implicit issuer"
behavior wherein the "iss" of the actor's "sub" is assumed to be the
same value as in the containing structure.  I'm not a fan of this type
of behavior in general, but if it's going to be used, you need to
document the possibility in some fashion.

I might also consider some language about how "the nested "act" claims
serve as a history trail that connects the initial request and subject
through the various delegation steps undertaken before reaching the
current actor.  In this sense, the current actor is considered to
include the entire authorization/delegation history, leading naturally
to the nested structure described here".  (But see also the other ballot
comment about this potentially leaking information to unauthorized
parties; it seems a more careful adjustment of the text is in order
here.)

Section 4.2

Is this really the first time we're defining "scope" as a JWT claim?  I
would have thought that would be defined long ago...

Section 4.4

Just to double-check: this is "things that can act as me" (where "me" is
the subject of the token containing this field), right?  The
parenthetical "May Act For" doesn't really help me decide whether this
claim represents the source or target of a permitted delegation, so
maybe "Allowed Impersonators" or similar would be more clear.  Even "act
as" or "act on behalf of" instead of "act for" would help me, I think.
[This would have trickle-down effects to later parts of the document as
well, e.g., the IANA Considerations.]
(Not that I claim to be a representative population, of course!)

It would probably also help greatly to note that when a subject_token is
presented to the token endpoint in a token exchange request, the
"may_act" claim in the subject token can be used by the authorization
service to determine whether the client (or party identified in the
actor_token) is authorized to engage in the requested delegation [or
impersonation].

Section 6

Let me say a bit more here about my perception of the potential privacy
considerations involved in the use of an error_uri (so we can figure out
if they are already discussed in a relevant document that we can cite;
JWT itself doesn't seem to cover this topic).  By sending an error_uri
instead of an error string, the server is in effect causing the client
to make an outbound request to a URL of the server's choosing.  If there
is a proxy between the client and server, this could result in the
server (and/or a party controlled by the server) learning additional
information about the client's identity/location.  A malicious server
could also attempt to construct a URI that, when retrieved by the
client, performs some unwanted side effect.  Defenses against this
latter scenario are pretty well known in the web comunity, but we may
want to be sure that the need for them is mentioned in a discoverable
place.

Appendix A.1.1

  In the following token exchange request, a client is requesting a
  token with impersonation semantics. [...]

What part of the request indicates that impersonation semantics are
requested?

Is the use of the "jwt" subject_token_type appropriate, given the
previous discussion about id_token/access_token being generally
preferred (as conveying more meaning)?

[Ballot discuss]
Thanks to everyone who worked on this document. I have a blocking issue that
should be easy to resolve, and a handful of more minor issues.

§2.1:

>  The client makes a token exchange request to the token endpoint with
>  an extension grant type by including the following parameters using
>  the "application/x-www-form-urlencoded" format

This document needs a normative citation for this media type.

My suggestion would be to cite REC-html5-20141028 section 4.10.22.6, as this
appears to be the most recent stable description of how to encode this media
type. I'd love to hear rationale behind other citations being more appropriate,
since I'm not entirely happy with the one I suggest above (given that it's been
superseded by HTML 5.2); but every other plausible citation I can find is even
less palatable (with HTML 5.2 itself having the drawback of not actually
defining how to encode the media type, instead pointing to an unstable,
unversioned document).

[Ballot comment]
Abstract:

>  This specification defines a protocol for an HTTP- and JSON- based

Nit: "...JSON-based..."

---------------------------------------------------------------------------

§1.1:

>  impersonates principal B, then in so far as any entity receiving such

Nit: "insofar"

---------------------------------------------------------------------------

§2.1:

>  The client makes a token exchange request to the token endpoint with
>  an extension grant type by including the following parameters using
>  the "application/x-www-form-urlencoded" format with a character
>  encoding of UTF-8 in the HTTP request entity-body:

I think there's an implication here that POST is used, but that probably needs
to be made explicit.

---------------------------------------------------------------------------

§2.2.1:

>  response using the "application/json" media type, as specified by
>  [RFC7159], and an HTTP 200 status code.  The parameters are

RFC 7159 has been replaced by RFC 8259.

---------------------------------------------------------------------------

§3:

>  urn:ietf:params:oauth:token-type:refresh_token
>    Indicates that the token is an OAuth 2.0 refreshe token issued by

nit: "refresh"

[Ballot comment]
Section 3:

If I understand this correctly:

"The distinction between an access token and a JWT is subtle."

I think it would be clearer if it said:

"The distinction between an access token type and a JWT token type is subtle."

Section 4.1:

What is the value of maintaining the whole delegation chain rather than expressing just the most recent delegation? Doesn't it potentially expose information about past exchanges unnecessarily?

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-oauth-token-exchange-14. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator understands that, upon approval of this document, there are six actions which we must complete.

First, in the OAuth URI registry located on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

six, new URIs are to be added as follows:

URN: urn:ietf:params:oauth:grant-type:token-exchange
Common Name: Token exchange grant type for OAuth 2.0
Change controller: IESG
Reference: Section 2.1 of [ RFC-to-be ]

URN: urn:ietf:params:oauth:token-type:access_token
Common Name: Token type URI for an OAuth 2.0 access token
Change controller: IESG
Reference: Section 3 of [[this specification]]

URN: urn:ietf:params:oauth:token-type:refresh_token
Common Name: Token type URI for an OAuth 2.0 refresh token
Change controller: IESG
Reference: Section 3 of [[this specification]]

URN: urn:ietf:params:oauth:token-type:id_token
Common Name: Token type URI for an ID Token
Change controller: IESG
Reference: Section 3 of [[this specification]]

URN: urn:ietf:params:oauth:token-type:saml1
Common Name: Token type URI for a base64url-encoded SAML 1.1 assertion
Change Controller: IESG
Reference: Section 3 of [[this specification]]

URN: urn:ietf:params:oauth:token-type:saml2
Common Name: Token type URI for a base64url-encoded SAML 2.0 assertion
Change Controller: IESG
Reference: Section 3 of [[this specification]]

As this document requests registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. Expert review will need to be completed before your document can be approved for publication as an RFC.

Second, in the OAuth Parameters registry also located on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

eight, new parameters are to be registered as follows:

Parameter name: resource
Parameter usage location: token request
Change controller: IESG
Reference: Section 2.1 of [ RFC-to-be ]

Parameter name: audience
Parameter usage location: token request
Change controller: IESG
Reference: Section 2.1 of [ RFC-to-be ]

Parameter name: requested_token_type
Parameter usage location: token request
Change controller: IESG
Reference: Section 2.1 of [ RFC-to-be ]

Parameter name: subject_token
Parameter usage location: token request
Change controller: IESG
Reference: Section 2.1 of [ RFC-to-be ]

Parameter name: subject_token_type
Parameter usage location: token request
Change controller: IESG
Reference: Section 2.1 of [ RFC-to-be ]

Parameter name: actor_token
Parameter usage location: token request
Change controller: IESG
Reference: Section 2.1 of [ RFC-to-be ]

Parameter name: actor_token_type
Parameter usage location: token request
Change controller: IESG
Reference: Section 2.1 of [ RFC-to-be ]

Parameter name: issued_token_type
Parameter usage location: token response
Change controller: IESG
Reference: Section 2.2.1 of [ RFC-to-be ]

As this also requests registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. Expert review will need to be completed before your document can be approved for publication as an RFC.

Third, in the OAuth Access Token Types registry also located on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

a single, new registration is to be made as follows:

Type name: N_A
Additional Token Endpoint Response Parameters: (none)
HTTP Authentication Scheme(s): (none)
Change controller: IESG
Reference: Section 2.2.1 of [ RFC-to-be ]

As this, too, requests registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. Expert review will need to be completed before your document can be approved for publication as an RFC.

Fourth, in the JSON Web Token Claims registry located on the JSON Web Token (JWT) registry page located at:

https://www.iana.org/assignments/jwt/

four, new claims are to be registered as follows:

Claim Name: "act"
Claim Description: Actor
Change Controller: IESG
Reference: Section 4.1 of [ RFC-to-be ]

Claim Name: "scope"
Claim Description: Scope Values
Change Controller: IESG
Reference: Section 4.2 of [ RFC-to-be ]

Claim Name: "client_id"
Claim Description: Client Identifier
Change Controller: IESG
Refernce: Section 4.3 of [ RFC-to-be ]

Claim Name: "may_act"
Claim Description: May Act For
Change Controller: IESG
Reference: Section 4.4 of [ RFC-to-be ]

As this section also requests registrations in a Specification Required (see RFC 8126) registry, the IESG-designated experts for the JSON Web Token Claims have asked that you send a review request to the mailing list jwt-reg-review@ietf.org. Expert review will need to be completed before your document can be approved for publication as an RFC.

Fifth, in the OAuth Token Introspection Response registry also located on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

two, new registrations are to be made as follows:

Claim Name: "act"
Claim Description: Actor
Change Controller: IESG
Reference: Section 4.1 of [ RFC-to-be ]

Claim Name: "may_act"
Claim Description: May Act For
Change Controller: IESG
Reference: Section 4.4 of [ RFC-to-be ]

As this, too, requests registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. Expert review will need to be completed before your document can be approved for publication as an RFC.

Sixth, in the OAuth Extensions Error Registry also located on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

a single, new error is to be registerd as follows:

Error Usage Location: token error response
Related Protocol Extension: OAuth 2.0 Token Exchange
Change Controller: IETF
Reference: Section 2.2.2 of [ RFC-to-be ]

As this, too, requests registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. Expert review will need to be completed before your document can be approved for publication as an RFC.

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

Thank you,

Sabrina Tanamal
Senior IANA Services Specialist

The following Last Call announcement was sent out (ends 2018-08-06):

From: The IESG
To: IETF-Announce
CC: ekr@rtfm.com, Rifaat Shekh-Yusef , draft-ietf-oauth-token-exchange@ietf.org, rifaat.ietf@gmail.com, oauth@ietf.org, Hannes Tschofenig , oauth-chairs@ietf.org
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (OAuth 2.0 Token Exchange) to Proposed Standard


The IESG has received a request from the Web Authorization Protocol WG
(oauth) to consider the following document: - 'OAuth 2.0 Token Exchange'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2018-08-06. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the beginning of
the Subject line to allow automated sorting.

Abstract


  This specification defines a protocol for an 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 file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-oauth-token-exchange/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-oauth-token-exchange/ballot/


No IPR declarations have been submitted directly on this I-D.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard,
Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this
type of RFC indicated in the title page header?

The draft-ietf-oauth-token-exchange-10 is a Standards Track document that extends OAuth
2.0 and defines a new protocol for Security Token Service (STS) to be used by OAuth elements
(e.g. Clients, Resource Servers, etc) to exchange one token for another.

(2) The IESG approval announcement includes a Document Announcement Write-Up.
Please provide such a Document Announcement Write-Up. Recent examples can be
found in the "Action" announcements for approved documents. The approval
announcement contains the following sections:

Technical Summary:
  This specification defines a protocol for an 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 specification extends the scope of the Authorization Server (AS) to act as an STS to
  allow the AS to exchange one token for another. The working group thinks that this is a
  useful Standards Track document.

Working Group Summary:
  The WG document is the result of the merge of two individual documents that tried to
  address this issue of token exchange: draft-jones-oauth-token-exchange and draft-
  campbell-oauth-sts.
  The scope of the first few revisions of the document was limited, and there was a long
  discussion of addressing a Token Chaining use case:
  https://mailarchive.ietf.org/arch/msg/oauth/pQRiMz0NjwcAG9Jazm8Aex40UX8/?qid=e6b492516cfa24bebbf8996009413d62
  The WG document was extended to address the Token Chaining use case.

  The individual and WG documents were reviewed by a large number of participants, with
  lively and long discussions on the mailing list and during the WG meetings.

  One participant, Denis (denis.ietf@free.fr), raised some privacy & security concerns with
  the WG document, which was not shared by the rest of the group. Denis was encouraged
  by the group to write a draft on the subject to allow for a better and clear understanding
  of his concerns, or discuss the security issues in the context of the OAuth Security Topics
  document.

Document Quality:
  The document has been implemented by Salesforce, Microsoft, Box, Indigo IAM, Unity
  IdM, and partial implementation by RedHat.
    https://medium.com/box-developer-blog/introducing-token-exchange-for-box-platform-3dcf7ab891b8
    https://indigo-dc.gitbooks.io/iam/content/doc/user-guide/oauth_token_exchange.html
    http://www.unity-idm.eu/documentation/unity-2.1.0/manual.html#_token_exchange
    http://www.keycloak.org/docs/latest/securing_apps/index.html#_token-exchange

Personnel:
  The document shepherd is Rifaat Shekh-Yusef.
  The responsible Area Director is Eric Rescorla.

(3) Briefly describe the review of this document that was performed by the Document
Shepherd. If this version of the document is not ready for publication, please explain
why the document is being forwarded to the IESG.

The document shepherd has reviewed several versions of this document, including the last one,
feels the document is ready.

(4) Does the document Shepherd have any concerns about the depth or breadth of the
reviews that have been performed?

The document shepherd has no concerns with the level of reviews, as the document was
discussed and reviewed by many participants.

(5) Do portions of the document need review from a particular or from broader
perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or
internationalization? If so, describe the review that took place.

Security review is always needed and appreciated.

(6) Describe any specific concerns or issues that the Document Shepherd has with this
document that the Responsible Area Director and/or the IESG should be aware of? For
example, perhaps he or she is uncomfortable with certain parts of the document, or
has concerns whether there really is a need for it. In any event, if the WG has
discussed those issues and has indicated that it still wishes to advance the document,
detail those concerns here.

The document shepherd has no such concerns.

(7) Has each author confirmed that any and all appropriate IPR disclosures required
for full conformance with the provisions of BCP 78 and BCP 79 have already been filed.
If not, explain why?

Yes.
https://www.ietf.org/mail-archive/web/oauth/current/msg17638.html
https://www.ietf.org/mail-archive/web/oauth/current/msg17639.html
https://www.ietf.org/mail-archive/web/oauth/current/msg17640.html
https://www.ietf.org/mail-archive/web/oauth/current/msg17646.html
https://www.ietf.org/mail-archive/web/oauth/current/msg17669.html

(8) Has an IPR disclosure been filed that references this document? If so, summarize
any WG discussion and conclusion regarding the IPR disclosures.

No such IPR disclosures.

(9) How solid is the WG consensus behind this document? Does it represent the strong
concurrence of a few individuals, with others being silent, or does the WG as a whole
understand and agree with it?

There is a solid support for this document from the WG, with the exception of the individual
mentioned above.

(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If
so, please summarise the areas of conflict in separate email messages to the
Responsible Area Director. (It should be in a separate email because this questionnaire
is publicly available.)

No such threat or discontent, with the exception of the individual mentioned above with his
privacy and security concerns.

(11) Identify any ID nits the Document Shepherd has found in this document. (See
http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate
checks are not enough; this check needs to be thorough.

One nit found:

** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259)


(12) Describe how the document meets any required formal review criteria, such as
the MIB Doctor, media type, and URI type reviews.

No such reviews are necessary.

(13) Have all references within this document been identified as either normative or
informative?

Yes.

(14) Are there normative references to documents that are not ready for advancement
or are otherwise in an unclear state? If such normative references exist, what is the
plan for their completion?

No such references.

(15) Are there downward normative references (see RFC 3967)? If so, list these
downward references to support the Area Director in the Last Call procedure.

No such references.

(16) Will publication of this document change the status of any existing RFCs? Are
those RFCs listed on the title page header, listed in the abstract, and discussed in the
introduction? If the RFCs are not listed in the Abstract and Introduction, explain why,
and point to the part of the document where the relationship of this document to the
other RFCs is discussed. If this information is not in the document, explain why the WG
considers it unnecessary.

No status change of any existing RFCs.

(17) Describe the Document Shepherd's review of the IANA considerations section,
especially with regard to its consistency with the body of the document. Confirm that
all protocol extensions that the document makes are associated with the appropriate
reservations in IANA registries. Confirm that any referenced IANA registries have been
clearly identified. Confirm that newly created IANA registries include a detailed
specification of the initial contents for the registry, that allocations procedures for
future registrations are defined, and a reasonable name for the new registry has been
suggested (see RFC 5226).

The IANA section is complete and correct.

(18) List any new IANA registries that require Expert Review for future allocations.
Provide any public guidance that the IESG would find useful in selecting the IANA
Experts for these new registries.

No new IANA registries.

(19) Describe reviews and automated checks performed by the Document Shepherd to
validate sections of the document written in a formal language, such as XML code, BNF
rules, MIB definitions, etc.

The document contains JSON-based examples, and these were validated using JSONLint.