Ping Identity

brian.d.campbell@gmail.com https://twitter.com/__b_c

Ping Identity

ve7jtb@ve7jtb.com http://www.thread-safe.com/

Microsoft

mbj@microsoft.com http://self-issued.info/

Security OAuth Working Group PKCE OAuth Token Binding This specification describes a Proof Key for Code Exchange (PKCE) method utilizing Token Binding over HTTP to cryptographically bind the OAuth 2.0 authorization code to a key pair on the client, which it proves possession of during the access token request with the authorization code.

This specification minimally describes an OAuth 2.0 PKCE method based on the Token Binding Protocol and Token Binding over HTTP. 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.

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.

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, and the terms "Provided", "Token Binding" and "Token Binding ID" defined by Token Binding over HTTP.

As defined in Proof Key for Code Exchange, 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 with all trailing pad ('=') characters omitted and without the inclusion of any line breaks or whitespace) of the SHA-256 hash 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.

Upon receipt of the authorization code, the client sends the access token request to the token endpoint. The Token Binding 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, 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). 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 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.

TBD

This specification requests registration of the following Code Challenge Method Parameter Name in the IANA "PKCE Code Challenge Methods" registry established by .

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

IANA

Dirk Balfanz, William Dennis (and others?) also provided input to this specification.

[[ to be removed by the RFC Editor before publication as an RFC ]] draft-campbell-oauth-tbpkce-00 Initial version.