< draft-ietf-oauth-token-exchange-17.txt   draft-ietf-oauth-token-exchange-18.txt >
OAuth Working Group M. Jones OAuth Working Group M. Jones
Internet-Draft A. Nadalin Internet-Draft A. Nadalin
Intended status: Standards Track Microsoft Intended status: Standards Track Microsoft
Expires: January 6, 2020 B. Campbell, Ed. Expires: January 7, 2020 B. Campbell, Ed.
Ping Identity Ping Identity
J. Bradley J. Bradley
Yubico Yubico
C. Mortimore C. Mortimore
Salesforce Salesforce
July 5, 2019 July 6, 2019
OAuth 2.0 Token Exchange OAuth 2.0 Token Exchange
draft-ietf-oauth-token-exchange-17 draft-ietf-oauth-token-exchange-18
Abstract Abstract
This specification defines a protocol for an HTTP- and JSON- based This specification defines a protocol for an HTTP- and JSON- based
Security Token Service (STS) by defining how to request and obtain Security Token Service (STS) by defining how to request and obtain
security tokens from OAuth 2.0 authorization servers, including security tokens from OAuth 2.0 authorization servers, including
security tokens employing impersonation and delegation. security tokens employing impersonation and delegation.
Status of This Memo Status of This Memo
skipping to change at page 1, line 39 skipping to change at page 1, line 39
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 6, 2020. This Internet-Draft will expire on January 7, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 44 skipping to change at page 2, line 44
7.2. OAuth Parameters Registration . . . . . . . . . . . . . . 21 7.2. OAuth Parameters Registration . . . . . . . . . . . . . . 21
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 21
7.3. OAuth Access Token Type Registration . . . . . . . . . . 22 7.3. OAuth Access Token Type Registration . . . . . . . . . . 22
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 22
7.4. JSON Web Token Claims Registration . . . . . . . . . . . 22 7.4. JSON Web Token Claims Registration . . . . . . . . . . . 22
7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 22
7.5. OAuth Token Introspection Response Registration . . . . . 23 7.5. OAuth Token Introspection Response Registration . . . . . 23
7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 23 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 23
7.6. OAuth Extensions Error Registration . . . . . . . . . . . 23 7.6. OAuth Extensions Error Registration . . . . . . . . . . . 23
7.6.1. Registry Contents . . . . . . . . . . . . . . . . . . 23 7.6.1. Registry Contents . . . . . . . . . . . . . . . . . . 23
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
8.1. Normative References . . . . . . . . . . . . . . . . . . 23 8.1. Normative References . . . . . . . . . . . . . . . . . . 24
8.2. Informative References . . . . . . . . . . . . . . . . . 24 8.2. Informative References . . . . . . . . . . . . . . . . . 24
Appendix A. Additional Token Exchange Examples . . . . . . . . . 25 Appendix A. Additional Token Exchange Examples . . . . . . . . . 26
A.1. Impersonation Token Exchange Example . . . . . . . . . . 25 A.1. Impersonation Token Exchange Example . . . . . . . . . . 26
A.1.1. Token Exchange Request . . . . . . . . . . . . . . . 25 A.1.1. Token Exchange Request . . . . . . . . . . . . . . . 26
A.1.2. Subject Token Claims . . . . . . . . . . . . . . . . 26 A.1.2. Subject Token Claims . . . . . . . . . . . . . . . . 26
A.1.3. Token Exchange Response . . . . . . . . . . . . . . . 26 A.1.3. Token Exchange Response . . . . . . . . . . . . . . . 27
A.1.4. Issued Token Claims . . . . . . . . . . . . . . . . . 27 A.1.4. Issued Token Claims . . . . . . . . . . . . . . . . . 27
A.2. Delegation Token Exchange Example . . . . . . . . . . . . 27 A.2. Delegation Token Exchange Example . . . . . . . . . . . . 28
A.2.1. Token Exchange Request . . . . . . . . . . . . . . . 27 A.2.1. Token Exchange Request . . . . . . . . . . . . . . . 28
A.2.2. Subject Token Claims . . . . . . . . . . . . . . . . 28 A.2.2. Subject Token Claims . . . . . . . . . . . . . . . . 28
A.2.3. Actor Token Claims . . . . . . . . . . . . . . . . . 29 A.2.3. Actor Token Claims . . . . . . . . . . . . . . . . . 29
A.2.4. Token Exchange Response . . . . . . . . . . . . . . . 29 A.2.4. Token Exchange Response . . . . . . . . . . . . . . . 29
A.2.5. Issued Token Claims . . . . . . . . . . . . . . . . . 29 A.2.5. Issued Token Claims . . . . . . . . . . . . . . . . . 30
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 30 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 31
Appendix C. Document History . . . . . . . . . . . . . . . . . . 30 Appendix C. Document History . . . . . . . . . . . . . . . . . . 31
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35
1. Introduction 1. Introduction
A security token is a set of information that facilitates the sharing A security token is a set of information that facilitates the sharing
of identity and security information in heterogeneous environments or of identity and security information in heterogeneous environments or
across security domains. Examples of security tokens include JSON across security domains. Examples of security tokens include JSON
Web Tokens (JWTs) [JWT] and SAML 2.0 Assertions Web Tokens (JWTs) [JWT] and SAML 2.0 Assertions
[OASIS.saml-core-2.0-os]. Security tokens are typically signed to [OASIS.saml-core-2.0-os]. Security tokens are typically signed to
achieve integrity and sometimes also encrypted to achieve achieve integrity and sometimes also encrypted to achieve
skipping to change at page 6, line 45 skipping to change at page 6, line 45
authentication and whether or not to allow unauthenticated or authentication and whether or not to allow unauthenticated or
unidentified clients are deployment decisions that are at the unidentified clients are deployment decisions that are at the
discretion of the authorization server. Note that omitting client discretion of the authorization server. Note that omitting client
authentication allows for a compromised token to be leveraged via an authentication allows for a compromised token to be leveraged via an
STS into other tokens by anyone possessing the compromised token. STS into other tokens by anyone possessing the compromised token.
Thus client authentication allows for additional authorization checks Thus client authentication allows for additional authorization checks
by the STS as to which entities are permitted to impersonate or by the STS as to which entities are permitted to impersonate or
receive delegations from other entities. receive delegations from other entities.
The client makes a token exchange request to the token endpoint with The client makes a token exchange request to the token endpoint with
an extension grant type using the HTTP "POST" method and including an extension grant type using the HTTP "POST" method. The following
the following parameters using the "application/x-www-form- parameters are included in the HTTP request entity-body using the
urlencoded" format with a character encoding of UTF-8 in the HTTP "application/x-www-form-urlencoded" format with a character encoding
request entity-body as described in Appendix B of RFC6749 [RFC6749]. of UTF-8 as described in Appendix B of RFC6749 [RFC6749].
grant_type grant_type
REQUIRED. The value "urn:ietf:params:oauth:grant-type:token- REQUIRED. The value "urn:ietf:params:oauth:grant-type:token-
exchange" indicates that a token exchange is being performed. exchange" indicates that a token exchange is being performed.
resource resource
OPTIONAL. A URI that indicates the target service or resource OPTIONAL. A URI that indicates the target service or resource
where the client intends to use the requested security token. where the client intends to use the requested security token.
This enables the authorization server to apply policy as This enables the authorization server to apply policy as
appropriate for the target, such as determining the type and appropriate for the target, such as determining the type and
skipping to change at page 10, line 44 skipping to change at page 10, line 44
representation of the security token, as it is in all representation of the security token, as it is in all
"*_token_type" parameters in this specification. If the issued "*_token_type" parameters in this specification. If the issued
token is not an access token or usable as an access token, then token is not an access token or usable as an access token, then
the "token_type" value "N_A" is used to indicate that an OAuth 2.0 the "token_type" value "N_A" is used to indicate that an OAuth 2.0
"token_type" identifier is not applicable in that context. "token_type" identifier is not applicable in that context.
expires_in expires_in
RECOMMENDED. The validity lifetime, in seconds, of the token RECOMMENDED. The validity lifetime, in seconds, of the token
issued by the authorization server. Oftentimes the client will issued by the authorization server. Oftentimes the client will
not have the inclination or capability to inspect the content of not have the inclination or capability to inspect the content of
the token and this parameter provides a consistent and token type the token and this parameter provides a consistent and token-type-
agnostic indication of how long the token can be expected to be agnostic indication of how long the token can be expected to be
valid. For example, the value 1800 denotes that the token will valid. For example, the value 1800 denotes that the token will
expire in thirty minutes from the time the response was generated. expire in thirty minutes from the time the response was generated.
scope scope
OPTIONAL, if the scope of the issued security token is identical OPTIONAL, if the scope of the issued security token is identical
to the scope requested by the client; otherwise, REQUIRED. to the scope requested by the client; otherwise, REQUIRED.
refresh_token refresh_token
OPTIONAL. A refresh token will typically not be issued when the OPTIONAL. A refresh token will typically not be issued when the
skipping to change at page 19, line 46 skipping to change at page 19, line 46
} }
Figure 9: Authorized Actor Claim Figure 9: Authorized Actor Claim
When included as a top-level member of an OAuth token introspection When included as a top-level member of an OAuth token introspection
response, "may_act" has the same semantics and format as the claim of response, "may_act" has the same semantics and format as the claim of
the same name. the same name.
5. Security Considerations 5. Security Considerations
Much of the guidance from Section 10 of [RFC6749], the Security
Considerations in The OAuth 2.0 Authorization Framework, is also
applicable here. Furthermore, [RFC6819] provides additional security
considerations for OAuth and [I-D.ietf-oauth-security-topics] has
updated security guidance based on deployment experience and new
threats that have emerged since OAuth 2.0 was originally published.
All of the normal security issues that are discussed in [JWT], All of the normal security issues that are discussed in [JWT],
especially in relationship to comparing URIs and dealing with especially in relationship to comparing URIs and dealing with
unrecognized values, also apply here. unrecognized values, also apply here.
In addition, both delegation and impersonation introduce unique In addition, both delegation and impersonation introduce unique
security issues. Any time one principal is delegated the rights of security issues. Any time one principal is delegated the rights of
another principal, the potential for abuse is a concern. The use of another principal, the potential for abuse is a concern. The use of
the "scope" claim is suggested to mitigate potential for such abuse, the "scope" claim is suggested to mitigate potential for such abuse,
as it restricts the contexts in which the delegated rights can be as it restricts the contexts in which the delegated rights can be
exercised. exercised.
skipping to change at page 24, line 38 skipping to change at page 24, line 46
RFC 7662, DOI 10.17487/RFC7662, October 2015, RFC 7662, DOI 10.17487/RFC7662, October 2015,
<https://www.rfc-editor.org/info/rfc7662>. <https://www.rfc-editor.org/info/rfc7662>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
8.2. Informative References 8.2. Informative References
[I-D.ietf-oauth-security-topics]
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"OAuth 2.0 Security Best Current Practice", draft-ietf-
oauth-security-topics-12 (work in progress), March 2019.
[OASIS.saml-core-1.1] [OASIS.saml-core-1.1]
Maler, E., Mishra, P., and R. Philpott, "Assertions and Maler, E., Mishra, P., and R. Philpott, "Assertions and
Protocol for the OASIS Security Assertion Markup Language Protocol for the OASIS Security Assertion Markup Language
(SAML) V1.1", OASIS Standard oasis-sstc-saml-core-1.1, (SAML) V1.1", OASIS Standard oasis-sstc-saml-core-1.1,
September 2003. September 2003.
[OASIS.saml-core-2.0-os] [OASIS.saml-core-2.0-os]
Cantor, S., Kemp, J., Philpott, R., and E. Maler, Cantor, S., Kemp, J., Philpott, R., and E. Maler,
"Assertions and Protocol for the OASIS Security Assertion "Assertions and Protocol for the OASIS Security Assertion
Markup Language (SAML) V2.0", OASIS Standard saml-core- Markup Language (SAML) V2.0", OASIS Standard saml-core-
skipping to change at page 25, line 19 skipping to change at page 25, line 31
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012, DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/info/rfc6750>. <https://www.rfc-editor.org/info/rfc6750>.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
<https://www.rfc-editor.org/info/rfc6755>. <https://www.rfc-editor.org/info/rfc6755>.
[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819,
DOI 10.17487/RFC6819, January 2013,
<https://www.rfc-editor.org/info/rfc6819>.
[RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland,
"Assertion Framework for OAuth 2.0 Client Authentication "Assertion Framework for OAuth 2.0 Client Authentication
and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521,
May 2015, <https://www.rfc-editor.org/info/rfc7521>. May 2015, <https://www.rfc-editor.org/info/rfc7521>.
[RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token
(JWT) Profile for OAuth 2.0 Client Authentication and (JWT) Profile for OAuth 2.0 Client Authentication and
Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May
2015, <https://www.rfc-editor.org/info/rfc7523>. 2015, <https://www.rfc-editor.org/info/rfc7523>.
skipping to change at page 30, line 32 skipping to change at page 31, line 11
} }
Figure 18: Issued Token Claims Figure 18: Issued Token Claims
Appendix B. Acknowledgements Appendix B. Acknowledgements
This specification was developed within the OAuth Working Group, This specification was developed within the OAuth Working Group,
which includes dozens of active and dedicated participants. It was which includes dozens of active and dedicated participants. It was
produced under the chairmanship of Hannes Tschofenig, Derek Atkins, produced under the chairmanship of Hannes Tschofenig, Derek Atkins,
and Rifaat Shekh-Yusef with Kathleen Moriarty, Stephen Farrell, Eric and Rifaat Shekh-Yusef with Kathleen Moriarty, Stephen Farrell, Eric
Rescorla, and Benjamin Kaduk serving as Security Area Directors. The Rescorla, Roman Danyliw, and Benjamin Kaduk serving as Security Area
following individuals contributed ideas, feedback, and wording to Directors. The following individuals contributed ideas, feedback,
this specification: and wording to this specification:
Caleb Baker, Vittorio Bertocci, Mike Brown, Thomas Broyer, William Caleb Baker, Vittorio Bertocci, Mike Brown, Thomas Broyer, William
Denniss, Vladimir Dzhuvinov, Phil Hunt, Benjamin Kaduk, Jason Denniss, Vladimir Dzhuvinov, Phil Hunt, Benjamin Kaduk, Jason
Keglovitz, Torsten Lodderstedt, Adam Lewis, James Manger, Nov Matake, Keglovitz, Torsten Lodderstedt, Adam Lewis, James Manger, Nov Matake,
Matt Miller, Hilarie Orman, Matthew Perry, Eric Rescorla, Justin Matt Miller, Hilarie Orman, Matthew Perry, Eric Rescorla, Justin
Richer, Adam Roach, Rifaat Shekh-Yusef, Scott Tomilson, and Hannes Richer, Adam Roach, Rifaat Shekh-Yusef, Scott Tomilson, and Hannes
Tschofenig. Tschofenig.
Appendix C. Document History Appendix C. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-18
o
-17 -17
o Editorial improvements and example fixes resulting from IESG o Editorial improvements and example fixes resulting from IESG
evaluation comments. evaluation comments.
o Added a pointer to RFC6749's Appendix B. on the "Use of o Added a pointer to RFC6749's Appendix B. on the "Use of
application/x-www-form-urlencoded Media Type" as a way of application/x-www-form-urlencoded Media Type" as a way of
providing a normative citation (by reference) for the media type. providing a normative citation (by reference) for the media type.
o Strengthened some of the wording in the privacy considerations to o Strengthened some of the wording in the privacy considerations to
bring it inline with RFC 7519 Sec. 12 and RFC 6749 Sec. 10.8. bring it inline with RFC 7519 Sec. 12 and RFC 6749 Sec. 10.8.
-16 -16
o Fixed typo and added an AD to Acknowledgements. o Fixed typo and added an AD to Acknowledgements.
 End of changes. 17 change blocks. 
24 lines changed or deleted 44 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/