RFC7636: Proof Key for Code Exchange by OAuth Public Clients

This RFC 7636 is used to improve the security of Authorization Code flow for public clients by sending extra “code_challenge” and “code_verifier” to the authorization server.

The code_challenge goes to the authorization endpoint, through the browser. The code_verifier goes to the token endpoint, from server to server. Someone who steals the code cannot use it without the code_verifier:

        sequenceDiagram
    autonumber
    participant User as User's browser<br/>(User Agent)
    participant Client
    box rgba(80, 120, 220, 0.12) CodeChallenge
        participant AS as Authorization Server
    end
    participant RS as Resource Server

    Note over Client: Generates a code_verifier<br/>and its code_challenge
    rect rgba(120, 120, 120, 0.08)
        Note over User,AS: Front channel (browser)
        Client-->>User: 302 Found → /authorize
        User->>AS: GET /authorize (code_challenge)
        Note over User,AS: The user logs in and approves
        AS-->>User: 302 Found → redirect_uri?code=…
        User->>Client: GET redirect_uri?code=…
    end
    rect rgba(120, 120, 120, 0.08)
        Note over Client,RS: Back channel (server to server)
        Client->>AS: POST /token (code, code_verifier)
        AS-->>Client: 200 OK + access token
        Client->>RS: GET /api (bearer token)
        RS-->>Client: 200 OK + resource
    end

  1. The client redirects the browser to the authorization endpoint.

  2. The request contains code_challenge and code_challenge_method. With S256, code_challenge is the SHA-256 hash of code_verifier, in base64url. CodeChallenge checks the format of code_challenge and the support of code_challenge_method. The save_authorization_code method of the grant stores them with the code.

  3. The authorization server redirects the browser to the client with a code.

  4. The client receives the code.

  5. The client sends the code and the code_verifier. CodeChallenge computes the challenge from code_verifier and compares it with the stored code_challenge. It returns invalid_grant if they differ.

  6. The authorization server returns an access token.

  7. The client calls the API of the Resource Server with the access token, in the Authorization: Bearer header.

  8. The Resource Server returns the protected resource.

The /authorize, /token and /api paths are examples.

Using RFC7636 in Authorization Code Grant

In order to apply proof key for code exchange, you need to register the CodeChallenge extension to AuthorizationCodeGrant. But before that, we need to re-design our AuthorizationCode database.

The new database SHOULD contain two more columns:

  1. code_challenge: A VARCHAR

  2. code_challenge_method: A VARCHAR

And the AuthorizationCodeGrant should record the code_challenge and code_challenge_method into database in save_authorization_code method:

class MyAuthorizationCodeGrant(AuthorizationCodeGrant):
    # YOU MAY NEED TO ADD "none" METHOD FOR AUTHORIZATION WITHOUT CLIENT SECRET
    TOKEN_ENDPOINT_AUTH_METHODS = ['client_secret_basic', 'client_secret_post', 'none']

    def save_authorization_code(self, code, request):
        # NOTICE BELOW
        code_challenge = request.payload.data.get('code_challenge')
        code_challenge_method = request.payload.data.get('code_challenge_method')
        auth_code = AuthorizationCode(
            code=code,
            client_id=request.client.client_id,
            redirect_uri=request.redirect_uri,
            scope=request.scope,
            user_id=request.user.id,
            code_challenge=code_challenge,
            code_challenge_method=code_challenge_method,
        )
        auth_code.save()
        return auth_code

Now you can register your AuthorizationCodeGrant with the extension:

from authlib.oauth2.rfc7636 import CodeChallenge
server.register_grant(MyAuthorizationCodeGrant, [CodeChallenge(required=True)])

With required=True, public clients must use PKCE. The check happens at the token endpoint: a public client that sends no code_verifier gets an invalid_request error. The authorization endpoint does not reject a request without code_challenge, but the code it returns cannot be exchanged.

With required=False, PKCE is optional for all clients.

In both modes:

  • If the authorization request contained a code_challenge, the token request must contain a matching code_verifier.

  • If the authorization request contained no code_challenge, a token request with a code_verifier is rejected.

  • Confidential clients may use PKCE, but are not required to.

Using code_challenge in Client

Read the Code Challenge section in the Web Clients.

It is also possible to add code_challenge in OAuth2Session, consider that we already have a session:

>>> from authlib.oauth2.rfc7636 import create_s256_code_challenge
>>> code_verifier = generate_token(48)
>>> code_challenge = create_s256_code_challenge(code_verifier)
>>> uri, state = session.create_authorization_url(authorize_url, code_challenge=code_challenge, code_challenge_method='S256')
>>> # visit uri, get the response
>>> authorization_response = 'https://example.com/auth?code=42..e9&state=d..t'
>>> token = session.fetch_token(token_endpoint, authorization_response=authorization_response, code_verifier=code_verifier)

API Reference

class authlib.oauth2.rfc7636.CodeChallenge(required=True)

CodeChallenge extension to Authorization Code Grant. It is used to improve the security of Authorization Code flow for public clients by sending extra “code_challenge” and “code_verifier” to the authorization server.

The AuthorizationCodeGrant SHOULD save the code_challenge and code_challenge_method into database when save_authorization_code. Then register this extension via:

server.register_grant(AuthorizationCodeGrant, [CodeChallenge(required=True)])
DEFAULT_CODE_CHALLENGE_METHOD = 'plain'

defaults to “plain” if not present in the request

SUPPORTED_CODE_CHALLENGE_METHOD = ['plain', 'S256']

supported code_challenge_method

get_authorization_code_challenge(authorization_code)

Get “code_challenge” associated with this authorization code. Developers MAY re-implement it in subclass, the default logic:

def get_authorization_code_challenge(self, authorization_code):
    return authorization_code.code_challenge
Parameters:

authorization_code – the instance of authorization_code

get_authorization_code_challenge_method(authorization_code)

Get “code_challenge_method” associated with this authorization code. Developers MAY re-implement it in subclass, the default logic:

def get_authorization_code_challenge_method(self, authorization_code):
    return authorization_code.code_challenge_method
Parameters:

authorization_code – the instance of authorization_code