oauth2.dev

S256

IESG

Registry Context

S256 derives the PKCE code challenge by applying SHA-256 to the ASCII-encoded code verifier and base64url-encoding the result.

Technical Summary

For S256, code_challenge is BASE64URL-ENCODE(SHA256(ASCII(code_verifier))). The token endpoint applies this transformation to the received code_verifier and compares the result with the associated code_challenge.

When Used

The client sends S256 as the code_challenge_method in the authorization request. The server associates that method and the code_challenge with the authorization code and later uses the bound method to verify the code_verifier.

Normative Requirements

Clients

MUST
1
  1. RFC 7636 - Section 4.2

    use "S256" as the code challenge transformation method.

    Condition: if the client is capable of using S256

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

REQUIRED
2
  1. RFC 7636 - Section 4.3

    send the code_challenge parameter in the authorization request.

    Condition: when using PKCE

    code_challenge REQUIRED. Code challenge.

  2. RFC 7636 - Section 4.5

    send the code_verifier parameter in the access token request.

    Condition: when redeeming the authorization code

    code_verifier REQUIRED. Code verifier

OPTIONAL
1
  1. RFC 7636 - Section 4.3

    send the code_challenge_method parameter in the authorization request.

    Condition: the parameter defaults to "plain" when absent

    code_challenge_method OPTIONAL, defaults to "plain" if not present

Servers

MUST NOT
1
  1. RFC 7636 - Section 4.4

    include the code_challenge value 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
1
  1. RFC 7636 - Section 4.4

    associate the code_challenge and code_challenge_method values with the authorization code.

    Condition: when issuing the authorization code

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

token endpoint

MUST
3
  1. RFC 7636 - Section 4.5

    use the code_challenge_method bound to the authorization code to verify the code_verifier.

    That is the method that the token endpoint MUST use to verify the "code_verifier".

  2. RFC 7636 - Section 4.6

    continue processing the token request as normal.

    Condition: if the calculated and associated code challenge values are equal

    If the values are equal, the token endpoint MUST continue processing as normal

  3. RFC 7636 - Section 4.6

    return an error response indicating "invalid_grant".

    Condition: if the calculated and associated code challenge values are not equal

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

Validation Guidance

error

Recognize and implement S256 as a supported PKCE code challenge transformation method.

error

Flag a client capable of S256 that uses another transformation method.

error

Require code_challenge in a PKCE authorization request and require code_challenge_method=S256 when S256 is used.

error

Associate the submitted code_challenge and code_challenge_method with the authorization code.

error

Do not expose code_challenge in client requests in a form extractable by other entities.

error

Require code_verifier in the access token request and verify it using the method bound to the authorization code.

error

For S256, compare BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) with the associated code_challenge.

error

Continue normal processing when the values match; otherwise return an invalid_grant error response.

Security Notes

RFC 7636 - Section 4.2

Clients capable of S256 must use it. RFC 7636 permits plain only when S256 cannot be supported for a technical reason and the client knows through out-of-band configuration that the server supports plain.

RFC 7636 - Section 4.4

The server must not expose code_challenge in client requests in a form that other entities can extract.

Reference

Section 4.2 of RFC7636

Details

Entry Id
S256
Code Challenge Method Parameter Name
S256
Change Controller
IESG
Reference
Section 4.2 of RFC7636