OAuth Working Group B. Campbell Internet-Draft J. Bradley Intended status: Standards Track Ping Identity Expires: January 9, 2017 M. Jones Microsoft July 8, 2016 A Token Binding method for OAuth 2.0 Proof Key for Code Exchange draft-campbell-oauth-tbpkce-00 Abstract This specification describes a Proof Key for Code Exchange (PKCE) [RFC7636] method utilizing Token Binding over HTTP [I-D.ietf-tokbind-https] to cryptographically bind the OAuth 2.0 [RFC6749] authorization code to a key pair on the client, which it proves possession of during the access token request with the authorization code. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on January 9, 2017. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must Campbell, et al. Expires January 9, 2017 [Page 1] Internet-Draft Token Binding PKCE July 2016 include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Notation and Conventions . . . . . . . . . . 2 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 2. Code Challenge . . . . . . . . . . . . . . . . . . . . . . . 3 3. Code Verifier . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Security Considerations . . . . . . . . . . . . . . . . . . . 4 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 5.1. PKCE Code Challenge Method Registration . . . . . . . . . 4 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 4 6. Normative References . . . . . . . . . . . . . . . . . . . . 4 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 5 Appendix B. Document History . . . . . . . . . . . . . . . . . . 5 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction This specification minimally describes an OAuth 2.0 [RFC6749] PKCE [RFC7636] method based on the Token Binding Protocol [I-D.ietf-tokbind-protocol] and Token Binding over HTTP [I-D.ietf-tokbind-https]. The general details and motivations of PKCE are discussed in that document and this specification defines only the additional pieces needed for a Token Binding PKCE method. 1.1. Requirements Notation and Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. 1.2. Terminology This specification uses the terms "authorization code", "authorization endpoint", "authorization server", "authorization request", "access token request", "client", and "token endpoint" defined by OAuth 2.0 [RFC6749], and the terms "Provided", "Token Binding" and "Token Binding ID" defined by Token Binding over HTTP [I-D.ietf-tokbind-https]. Campbell, et al. Expires January 9, 2017 [Page 2] Internet-Draft Token Binding PKCE July 2016 2. Code Challenge As defined in Proof Key for Code Exchange [RFC7636], the client sends the code challenge as part of the OAuth 2.0 Authorization Request with the two additional parameters: "code_challenge" and "code_challenge_method". For the Token Binding method of PKCE defined herein, "tb2" is used for the value of the "code_challenge_method" parameter. The value of the "code_challenge" parameter is the base64url encoding (per Section 5 of [RFC4648] with all trailing pad ('=') characters omitted and without the inclusion of any line breaks or whitespace) of the SHA-256 hash [RFC6234] of the Provided Token Binding ID that the client will use when calling the authorization server's token endpoint. Note that, prior to making the authorization request, the client may need to establish a TLS connection between itself and the authorization server's token endpoint in order to obtain the appropriate Token Binding ID. When the authorization server issues the authorization code in the authorization response, it associates the code challenge and method values with the authorization code so it can be verified later when the code is presented in the access token request. 3. Code Verifier Upon receipt of the authorization code, the client sends the access token request to the token endpoint. The Token Binding Protocol [I-D.ietf-tokbind-protocol] is negotiated on the TLS connection between the client and the authorization server and the "Sec-Token- Binding" header, as defined in Token Binding over HTTP [I-D.ietf-tokbind-https], is included in the access token request. The authorization server extracts the Provided Token Binding ID from the header value, hashes it with SHA-256, and compares it to the "code_challenge" value previously associated with the authorization code. If the values match, the token endpoint MUST continue processing as normal (as defined by OAuth 2.0 [RFC6749]). If the values do not match, an error response indicating "invalid_grant" MUST be returned. The "Sec-Token-Binding" header contains sufficient information for verification of the authorization code and its association to the original authorization request. However, PKCE [RFC7636] requires that a "code_verifier" parameter be sent with the access token request, so the static value "provided" is used to meet that requirement and indicate that the Provided Token Binding ID is used for the verification. Campbell, et al. Expires January 9, 2017 [Page 3] Internet-Draft Token Binding PKCE July 2016 4. Security Considerations TBD 5. IANA Considerations 5.1. PKCE Code Challenge Method Registration This specification requests registration of the following Code Challenge Method Parameter Name in the IANA "PKCE Code Challenge Methods" registry [IANA.OAuth.Parameters] established by [RFC7636]. 5.1.1. Registry Contents o Code Challenge Method Parameter Name: tb2 o Change controller: IESG o Specification document(s): Section 2 of [[ this specification ]] 6. Normative References [I-D.ietf-tokbind-https] Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. Hodges, "Token Binding over HTTP", draft-ietf-tokbind- https-03 (work in progress), March 2016. [I-D.ietf-tokbind-protocol] Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. Hodges, "The Token Binding Protocol Version 1.0", draft- ietf-tokbind-protocol-06 (work in progress), May 2016. [IANA.OAuth.Parameters] IANA, "OAuth Parameters", . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, . [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 10.17487/RFC6234, May 2011, . Campbell, et al. Expires January 9, 2017 [Page 4] Internet-Draft Token Binding PKCE July 2016 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, DOI 10.17487/RFC7636, September 2015, . Appendix A. Acknowledgements Dirk Balfanz, William Dennis (and others?) also provided input to this specification. Appendix B. Document History [[ to be removed by the RFC Editor before publication as an RFC ]] draft-campbell-oauth-tbpkce-00 o Initial version. Authors' Addresses Brian Campbell Ping Identity Email: brian.d.campbell@gmail.com URI: https://twitter.com/__b_c John Bradley Ping Identity Email: ve7jtb@ve7jtb.com URI: http://www.thread-safe.com/ Michael B. Jones Microsoft Email: mbj@microsoft.com URI: http://self-issued.info/ Campbell, et al. Expires January 9, 2017 [Page 5]