code_
Registry Context
`code_verifier` is the high-entropy PKCE value that the client creates and sends in the token request. The token endpoint checks it against the code challenge associated with the authorization code.
Technical Summary
In PKCE, the client includes `code_verifier` in the OAuth 2.0 access token request. The token endpoint applies the `code_challenge_method` associated with the authorization code and compares the result with the associated `code_challenge`; a mismatch results in an `invalid_grant` error.
When Used
Created for an OAuth 2.0 authorization request and subsequently sent when exchanging the resulting authorization code at the token endpoint.
Normative Requirements
Clients
RFC 7636 - Section 4.5
include the `code_verifier` parameter in the OAuth 2.0 access token request..
Condition: When exchanging the authorization code at the token endpoint using PKCE.
code_verifier REQUIRED. Code verifier
RFC 7636 - Section 4.1
create a `code_verifier` with enough entropy to make guessing it impractical..
Condition: When creating a code verifier.
The code verifier SHOULD have enough entropy to make it impractical to guess the value.
RFC 7636 - Section 7.1
create a `code_verifier` with at least 256 bits of entropy..
Condition: When creating a code verifier.
The client SHOULD create a "code_verifier" with a minimum of 256 bits of entropy.
RFC 7636 - Section 4.1
use the output of a suitable random number generator to create a 32-octet sequence for the verifier..
Condition: When creating a code verifier.
It is RECOMMENDED that the output of a suitable random number generator be used to create a 32-octet sequence.
token endpoint
RFC 7636 - Section 4.5
use the `code_challenge_method` associated with the authorization code to verify the `code_verifier`..
Condition: When processing the token request.
That is the method that the token endpoint MUST use to verify the "code_verifier".
RFC 7636 - Section 4.6
continue processing the token request normally..
Condition: When the value derived from `code_verifier` equals the associated `code_challenge`.
If the values are equal, the token endpoint MUST continue processing as normal.
RFC 7636 - Section 4.6
return an error response indicating `invalid_grant`..
Condition: When the value derived from `code_verifier` does not equal the associated `code_challenge`.
If the values are not equal, an error response indicating "invalid_grant" ... MUST be returned.
Validation Guidance
Check that `code_verifier` contains 43 to 128 unreserved characters: letters, digits, `-`, `.`, `_`, or `~`.
Check that the verifier has enough entropy to make guessing impractical, preferably at least 256 bits.
Prefer constructing the verifier from a suitable random 32-octet sequence.
Require the `code_verifier` parameter in a PKCE token request.
Verify `code_verifier` using the `code_challenge_method` associated with the authorization code.
Continue the token exchange normally when the derived value equals the associated challenge.
Return `invalid_grant` when the derived value does not equal the associated challenge.
Security Notes
RFC 7636 - Section 7.1
The security model relies on an attacker being unable to learn or guess the code verifier; it therefore needs to be cryptographically random and have high entropy.
Reference
Details
- Entry Id
code_verifier - Name
code_verifier - Parameter Usage Location
token request- Change Controller
IESG- Reference
RFC7636