RFC7636 - Proof Key for Code Exchange by OAuth Public Clients

Abstract

OAuth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the authorization code interception attack. This specification describes the attack as well as a technique to mitigate against the threat through the use of Proof Key for Code Exchange (PKCE, pronounced "pixy").

1. Introduction

In this attack, the attacker intercepts the authorization code returned from the authorization endpoint within a communication path not protected by Transport Layer Security (TLS), such as inter- application communication within the client’s operating system.

To mitigate this attack, this extension utilizes a dynamically created cryptographically random key called "code verifier". A unique code verifier is created for every authorization request, and its transformed value, called "code challenge", is sent to the authorization server to obtain the authorization code. The authorization code obtained is then sent to the token endpoint with the "code verifier", and the server compares it with the previously received request code so that it can perform the proof of possession of the "code verifier" by the client.

1.1 Protocol FLow

A. The client creates and records a secret named the "codeverifier" and derives a transformed version "t(codeverifier)" (referred to as the "codechallenge"), which is sent in the OAuth 2.0 Authorization Request along with the transformation method "tm".

B. The Authorization Endpoint responds as usual but records "t(code_verifier)" and the transformation method.

C. The client then sends the authorization code in the Access Token Request as usual but includes the "code_verifier" secret generated at (A).

D. The authorization server transforms "code_verifier" and compares it to "t(cod

3. Terminology

code verifier A cryptographically random string that is used to correlate the authorization request to the token request.

code challenge A challenge derived from the code verifier that is sent in the authorization request, to be verified against later.

code challenge method A method that was used to derive code challenge.

4. Protocol

4.1 Client Creates a Code Verifier

The client first creates a code verifier, "code_verifier", for each OAuth 2.0 [RFC6749] Authorization Request

4.2. Client Creates the Code Challenge

The client then creates a code challenge derived from the code verifier by using one of the following transformations on the code verifier:

plain codechallenge = codeverifier

S256 codechallenge = BASE64URL-ENCODE(SHA256(ASCII(codeverifier)))

If the client is capable of using "S256", it MUST use "S256"

4.3. Client Sends the Code Challenge with the Authorization Request

The client sends both the code_challenge and the code_challenge_method in the OAuth authorization request.

4.4. Server Returns the Code

When the server issues the authorization code in the authorization response, it MUST associate the "codechallenge" and "codechallenge_method" values with the authorization code so it can be verified later.

The server MUST NOT include the "code_challenge" value in client requests in a form that other entities can extract.

4.5. Client Sends the Authorization Code and the Code Verifier to the Token Endpoint

In addition to the authorization code the client also sends the code_verifierto the authorization server in the /token OAuth HTTP request.

4.6. Server Verifies code_verifier before Returning the Tokens

Upon receipt of the request at the token endpoint, the server verifies it by calculating the code challenge from the received "codeverifier" and comparing it with the previously associated "codechallenge", after first transforming it according to the "codechallengemethod" method specified by the client.

7. Security Considerations

7.1. Entropy of the code_verifier

The security model relies on the fact that the code verifier is not learned or guessed by the attacker.

7.2. Protection against Eavesdroppers

The "S256" method protects against eavesdroppers observing or intercepting the "code_challenge", because the challenge cannot be used without the verifier.

Because of this, "plain" SHOULD NOT be used and exists only for compatibility with deployed implementations where the request path is already protected.