oauth2.dev

code_challenge_methods_supported

IESG

Registry Context

Advertises the PKCE code challenge methods supported by an OAuth authorization server. Under RFC 8414, omission means that the server does not support PKCE. RFC 9700 now requires authorization servers to support PKCE and recommends publishing this member, although a deployment-specific PKCE detection mechanism may be used instead.

Technical Summary

An optional authorization server metadata member containing a JSON array of supported PKCE code_challenge_method values from the IANA PKCE Code Challenge Methods registry. As a multiple-valued claim, it must be omitted rather than represented by an empty array.

When Used

Used in OAuth Authorization Server Metadata responses so clients can detect PKCE support and select a supported challenge method.

Normative Requirements

Clients

MUST NOT
1
  1. RFC 7636 - Section 7.2

    downgrade to plain.

    Condition: after trying S256

    Clients MUST NOT downgrade to "plain" after trying the "S256" method.

MUST
1
  1. RFC 7636 - Section 4.2

    use S256.

    Condition: if capable of using S256

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

SHOULD
1
  1. RFC 9700 - Section 2.1.1

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

    Condition: when using PKCE

    When using PKCE, clients SHOULD use PKCE code challenge methods that do not expose the PKCE verifier in the authorization request.

Authorization servers

MUST
4
  1. RFC 7636 - Section 7.2

    encrypt a plain code challenge so that only the server can decrypt and extract it.

    Condition: when returning the code challenge inside an authorization code to implement a stateless server

    If the code challenge method is "plain" and the code challenge is to be returned inside authorization "code" to achieve a stateless server, it MUST be encrypted in such a manner that only the server can decrypt and extract it.

  2. RFC 8414 - Section 3.2

    omit code_challenge_methods_supported rather than return an empty array.

    Condition: when it would contain zero elements

    Claims with zero elements MUST be omitted from the response.

  3. RFC 9700 - Section 2.1.1

    support PKCE.

    Authorization servers MUST support PKCE.

  4. RFC 9700 - Section 2.1.1

    provide a way for clients to detect its PKCE support.

    Authorization servers MUST provide a way to detect their support for PKCE.

RECOMMENDED
1
  1. RFC 9700 - Section 2.1.1

    publish code_challenge_methods_supported in its authorization server metadata with the supported PKCE challenge methods.

    It is RECOMMENDED for authorization servers to publish the element code_challenge_methods_supported in their Authorization Server Metadata containing the supported PKCE challenge methods.

MAY
1
  1. RFC 9700 - Section 2.1.1

    use a deployment-specific way to ensure or determine its PKCE support instead of publishing this metadata member.

    Authorization servers MAY instead provide a deployment-specific way to ensure or determine PKCE support by the authorization server.

OPTIONAL
1
  1. RFC 8414 - Section 2

    include code_challenge_methods_supported as a JSON array of supported PKCE code challenge methods.

    OPTIONAL. JSON array containing a list of Proof Key for Code Exchange (PKCE) code challenge methods supported by this authorization server.

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.

implementation

SHOULD NOT
1
  1. RFC 7636 - Section 7.2

    use the plain code challenge method.

    Condition: except for compatibility with deployed implementations whose request path is already protected

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

SHOULD
1
  1. RFC 7636 - Section 7.2

    use S256 or another cryptographically secure code challenge method extension.

    The "S256" code challenge method or other cryptographically secure code challenge method extension SHOULD be used.

new implementation

SHOULD NOT
1
  1. RFC 7636 - Section 7.2

    use the plain code challenge method.

    Condition: unless S256 cannot be supported for a technical reason

    The "plain" method SHOULD NOT be used in new implementations, unless they cannot support "S256" for some technical reason.

processor

MUST NOT
1
  1. RFC 8414 - Section 4

    apply Unicode normalization to the metadata member name or method values during comparison.

    Condition: when comparing JSON strings with other Unicode strings

    Unicode Normalization MUST NOT be applied at any point to either the JSON string or the string it is to be compared against.

MUST
1
  1. RFC 8414 - Section 4

    compare the metadata member name and method values using Unicode code-point equality.

    Condition: when comparing JSON strings with other Unicode strings

    Comparisons between the two strings MUST be performed as a Unicode code-point-to-code-point equality comparison.

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 to this end.

Validation Guidance

error

If present, code_challenge_methods_supported must be a JSON array of strings naming PKCE challenge methods supported by the authorization server.

error

Validate method names against the IANA PKCE Code Challenge Methods registry.

error

Reject or flag an empty code_challenge_methods_supported array; the member must be omitted instead.

error

Compare member names and method values using exact Unicode code-point equality without Unicode normalization.

error

Flag authorization servers that provide no way for clients to detect PKCE support.

warning

Recommend publishing code_challenge_methods_supported when PKCE detection is not provided through a deployment-specific mechanism.

warning

Warn when plain is advertised without S256 because clients should use a method that does not expose the verifier and S256-capable clients must use S256.

warning

Warn clients not to retry with plain after an S256 failure.

Security Notes

RFC 7636 - Section 7.2

S256 prevents an observed code challenge from being used without the verifier. With plain, the challenge equals the verifier, so plain does not protect against eavesdropping on the initial authorization request.

RFC 7636 - Section 7.2

An S256 failure can indicate a faulty server or an attempted downgrade attack; clients must not respond by downgrading to plain.

RFC 9700 - Section 2.1.1

RFC 9700 requires authorization servers to support PKCE and requires public clients to use it for protection against authorization code injection and misuse.

Reference

Details

Entry Id
code_challenge_methods_supported
Metadata Name
code_challenge_methods_supported
Metadata Description
PKCE code challenge methods supported by this authorization server
Change Controller
IESG
Reference
RFC8414 - Section 2