idnits 2.17.1 draft-campbell-oauth-tbpkce-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC6749], [RFC7636], [I-D.ietf-tokbind-https]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2016) is 2841 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-18) exists of draft-ietf-tokbind-https-03 == Outdated reference: A later version (-19) exists of draft-ietf-tokbind-protocol-06 ** Downref: Normative reference to an Informational RFC: RFC 6234 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group B. Campbell 3 Internet-Draft J. Bradley 4 Intended status: Standards Track Ping Identity 5 Expires: January 9, 2017 M. Jones 6 Microsoft 7 July 8, 2016 9 A Token Binding method for OAuth 2.0 Proof Key for Code Exchange 10 draft-campbell-oauth-tbpkce-00 12 Abstract 14 This specification describes a Proof Key for Code Exchange (PKCE) 15 [RFC7636] method utilizing Token Binding over HTTP 16 [I-D.ietf-tokbind-https] to cryptographically bind the OAuth 2.0 17 [RFC6749] authorization code to a key pair on the client, which it 18 proves possession of during the access token request with the 19 authorization code. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 9, 2017. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Requirements Notation and Conventions . . . . . . . . . . 2 57 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. Code Challenge . . . . . . . . . . . . . . . . . . . . . . . 3 59 3. Code Verifier . . . . . . . . . . . . . . . . . . . . . . . . 3 60 4. Security Considerations . . . . . . . . . . . . . . . . . . . 4 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 62 5.1. PKCE Code Challenge Method Registration . . . . . . . . . 4 63 5.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 4 64 6. Normative References . . . . . . . . . . . . . . . . . . . . 4 65 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 5 66 Appendix B. Document History . . . . . . . . . . . . . . . . . . 5 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 5 69 1. Introduction 71 This specification minimally describes an OAuth 2.0 [RFC6749] PKCE 72 [RFC7636] method based on the Token Binding Protocol 73 [I-D.ietf-tokbind-protocol] and Token Binding over HTTP 74 [I-D.ietf-tokbind-https]. The general details and motivations of 75 PKCE are discussed in that document and this specification defines 76 only the additional pieces needed for a Token Binding PKCE method. 78 1.1. Requirements Notation and Conventions 80 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 81 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 82 "OPTIONAL" in this document are to be interpreted as described in RFC 83 2119 [RFC2119]. 85 1.2. Terminology 87 This specification uses the terms "authorization code", 88 "authorization endpoint", "authorization server", "authorization 89 request", "access token request", "client", and "token endpoint" 90 defined by OAuth 2.0 [RFC6749], and the terms "Provided", "Token 91 Binding" and "Token Binding ID" defined by Token Binding over HTTP 92 [I-D.ietf-tokbind-https]. 94 2. Code Challenge 96 As defined in Proof Key for Code Exchange [RFC7636], the client sends 97 the code challenge as part of the OAuth 2.0 Authorization Request 98 with the two additional parameters: "code_challenge" and 99 "code_challenge_method". 101 For the Token Binding method of PKCE defined herein, "tb2" is used 102 for the value of the "code_challenge_method" parameter. 104 The value of the "code_challenge" parameter is the base64url encoding 105 (per Section 5 of [RFC4648] with all trailing pad ('=') characters 106 omitted and without the inclusion of any line breaks or whitespace) 107 of the SHA-256 hash [RFC6234] of the Provided Token Binding ID that 108 the client will use when calling the authorization server's token 109 endpoint. Note that, prior to making the authorization request, the 110 client may need to establish a TLS connection between itself and the 111 authorization server's token endpoint in order to obtain the 112 appropriate Token Binding ID. 114 When the authorization server issues the authorization code in the 115 authorization response, it associates the code challenge and method 116 values with the authorization code so it can be verified later when 117 the code is presented in the access token request. 119 3. Code Verifier 121 Upon receipt of the authorization code, the client sends the access 122 token request to the token endpoint. The Token Binding Protocol 123 [I-D.ietf-tokbind-protocol] is negotiated on the TLS connection 124 between the client and the authorization server and the "Sec-Token- 125 Binding" header, as defined in Token Binding over HTTP 126 [I-D.ietf-tokbind-https], is included in the access token request. 127 The authorization server extracts the Provided Token Binding ID from 128 the header value, hashes it with SHA-256, and compares it to the 129 "code_challenge" value previously associated with the authorization 130 code. If the values match, the token endpoint MUST continue 131 processing as normal (as defined by OAuth 2.0 [RFC6749]). If the 132 values do not match, an error response indicating "invalid_grant" 133 MUST be returned. 135 The "Sec-Token-Binding" header contains sufficient information for 136 verification of the authorization code and its association to the 137 original authorization request. However, PKCE [RFC7636] requires 138 that a "code_verifier" parameter be sent with the access token 139 request, so the static value "provided" is used to meet that 140 requirement and indicate that the Provided Token Binding ID is used 141 for the verification. 143 4. Security Considerations 145 TBD 147 5. IANA Considerations 149 5.1. PKCE Code Challenge Method Registration 151 This specification requests registration of the following Code 152 Challenge Method Parameter Name in the IANA "PKCE Code Challenge 153 Methods" registry [IANA.OAuth.Parameters] established by [RFC7636]. 155 5.1.1. Registry Contents 157 o Code Challenge Method Parameter Name: tb2 158 o Change controller: IESG 159 o Specification document(s): Section 2 of [[ this specification ]] 161 6. Normative References 163 [I-D.ietf-tokbind-https] 164 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 165 Hodges, "Token Binding over HTTP", draft-ietf-tokbind- 166 https-03 (work in progress), March 2016. 168 [I-D.ietf-tokbind-protocol] 169 Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. 170 Hodges, "The Token Binding Protocol Version 1.0", draft- 171 ietf-tokbind-protocol-06 (work in progress), May 2016. 173 [IANA.OAuth.Parameters] 174 IANA, "OAuth Parameters", 175 . 177 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 178 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 179 RFC2119, March 1997, 180 . 182 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 183 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 184 . 186 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 187 (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 188 10.17487/RFC6234, May 2011, 189 . 191 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 192 RFC 6749, DOI 10.17487/RFC6749, October 2012, 193 . 195 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 196 for Code Exchange by OAuth Public Clients", RFC 7636, DOI 197 10.17487/RFC7636, September 2015, 198 . 200 Appendix A. Acknowledgements 202 Dirk Balfanz, William Dennis (and others?) also provided input to 203 this specification. 205 Appendix B. Document History 207 [[ to be removed by the RFC Editor before publication as an RFC ]] 209 draft-campbell-oauth-tbpkce-00 211 o Initial version. 213 Authors' Addresses 215 Brian Campbell 216 Ping Identity 218 Email: brian.d.campbell@gmail.com 219 URI: https://twitter.com/__b_c 221 John Bradley 222 Ping Identity 224 Email: ve7jtb@ve7jtb.com 225 URI: http://www.thread-safe.com/ 227 Michael B. Jones 228 Microsoft 230 Email: mbj@microsoft.com 231 URI: http://self-issued.info/