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 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
• 1.1. Requirements Notation and Conventions
• 1.2. Terminology
• 2. Code Challenge
• 3. Code Verifier
• 4. Security Considerations
• 5. IANA Considerations
• 5.1. PKCE Code Challenge Method Registration
• 5.1.1. Registry Contents
• 6. Normative References
• Appendix A. Acknowledgements
• Appendix B. Document History
• Authors' Addresses

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].

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.

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

• Code Challenge Method Parameter Name: tb2
• Change controller: IESG
• Specification document(s): Section 2 of [[ this specification ]]

6. Normative References

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

• Initial version.

Authors' Addresses