oauth2.dev

code_challenge

IESG

Registry Context

PKCE challenge value sent in an OAuth authorization request to bind the authorization code to the client that initiated the request.

Technical Summary

The client derives code_challenge from code_verifier using a registered transformation and sends it in the authorization request. The authorization server binds it to the authorization code and verifies the corresponding code_verifier at the token endpoint. Current security guidance favors S256 because it does not expose the verifier.

When Used

During OAuth 2.0 authorization code flows that use PKCE; RFC 9700 requires PKCE for public clients and recommends it for confidential clients.

Normative Requirements

Clients

MUST
1

  1. RFC 7636 - Section 4.2

    Use the S256 transformation when capable of supporting it..

    Condition: If the client is capable of using S256.

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

REQUIRED
1

  1. RFC 7636 - Section 4.3

    Include code_challenge in the OAuth 2.0 authorization request when using PKCE..

    Condition: When sending a PKCE authorization request.

    code_challenge REQUIRED. Code challenge.

SHOULD
1

  1. RFC 9700 - Section 2.1.1

    Use a PKCE code challenge method that does not expose the verifier in the authorization request..

    Condition: When using PKCE.

    clients SHOULD use PKCE code challenge methods that do not expose the PKCE verifier

Authorization servers

MUST NOT
1

  1. RFC 7636 - Section 4.4

    Include code_challenge in client requests in a form extractable by other entities..

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

MUST
4

  1. RFC 7636 - Section 4.4

    Associate the code_challenge and code_challenge_method values with the authorization code for later verification..

    Condition: When issuing an authorization code in the authorization response.

    it MUST associate the "code_challenge" and "code_challenge_method" values with the authorization code

  2. RFC 9700 - Section 2.1.1

    Support PKCE..

    Authorization servers MUST support PKCE

  3. RFC 9700 - Section 2.1.1

    Enforce correct use of code_verifier at the token endpoint..

    Condition: If the client supplied a valid code_challenge in the authorization request.

    the authorization server MUST enforce the correct usage of code_verifier at the token endpoint

  4. RFC 9700 - Section 2.1.1

    Accept a token request containing code_verifier only when code_challenge was present in the corresponding authorization request..

    Condition: To mitigate PKCE downgrade attacks.

    Authorization servers MUST mitigate PKCE downgrade attacks by ensuring that a token request containing a code_verifier parameter is accepted only if a code_challenge parameter was present

client and authorization server

MUST
1

  1. RFC 9700 - Section 2.1.1

    Ensure that the PKCE challenge is transaction-specific and securely bound to the client and the user agent in which the transaction began..

    Condition: When PKCE is used.

    the PKCE challenge ... MUST be transaction-specific and securely bound to the client and the user agent

confidential client

RECOMMENDED
1

  1. RFC 9700 - Section 2.1.1

    Use PKCE to protect against authorization code misuse and injection..

    Condition: When using the authorization code grant.

    For confidential clients, the use of PKCE ... is RECOMMENDED

public client

MUST
1

  1. RFC 9700 - Section 2.1.1

    Use PKCE to prevent authorization code injection and misuse..

    Condition: When using the authorization code grant.

    Public clients MUST use PKCE

token endpoint

MUST
2

  1. RFC 7636 - Section 4.6

    Continue normal OAuth 2.0 processing when the transformed code_verifier equals the associated code_challenge..

    Condition: If the compared values are equal.

    the token endpoint MUST continue processing as normal

  2. RFC 7636 - Section 4.6

    Return an invalid_grant error when the transformed code_verifier does not equal the associated code_challenge..

    Condition: If the compared values are not equal.

    an error response indicating "invalid_grant" ... MUST be returned

Validation Guidance

error

Reject a PKCE authorization request that omits code_challenge.

error

Validate code_challenge against the RFC 7636 ABNF: 43 to 128 unreserved characters.

warning

Use S256 unless the client cannot support it for a technical reason and knows through out-of-band configuration that plain is supported.

error

Bind code_challenge and code_challenge_method to the authorization code without exposing code_challenge in an extractable client-request form.

error

At the token endpoint, compare the transformed code_verifier with the associated code_challenge; continue on equality and return invalid_grant on mismatch.

error

Require public clients to use PKCE and recommend PKCE for confidential clients using the authorization code grant.

error

Ensure each code_challenge is transaction-specific and bound to the initiating client and user agent.

error

Ensure the authorization server supports PKCE and rejects token requests containing code_verifier when the corresponding authorization request lacked code_challenge.

Security Notes

RFC 9700 - Section 2.1.1

RFC 9700 identifies S256 as the only currently defined challenge method that does not expose the PKCE verifier in the authorization request.

RFC 9700 - Section 2.1.1

A constant or improperly bound code_challenge does not provide the required transaction-specific protection against authorization code injection and misuse.

Reference

RFC7636

Details

Entry Id
code_challenge
Name
code_challenge
Parameter Usage Location
authorization request
Change Controller
IESG
Reference
RFC7636