@@ -12,6 +12,58 @@ This :rfc:`7636` is used to improve the security of Authorization Code flow
1212for public clients by sending extra "code_challenge" and "code_verifier"
1313to the authorization server.
1414
15+ The ``code_challenge `` goes to the authorization endpoint, through the
16+ browser. The ``code_verifier `` goes to the token endpoint, from server to
17+ server. Someone who steals the code cannot use it without the
18+ ``code_verifier ``:
19+
20+ .. mermaid ::
21+
22+ sequenceDiagram
23+ autonumber
24+ participant User as User's browser<br/>(User Agent)
25+ participant Client
26+ box rgba(80, 120, 220, 0.12) CodeChallenge
27+ participant AS as Authorization Server
28+ end
29+ participant RS as Resource Server
30+
31+ Note over Client: Generates a code_verifier<br/>and its code_challenge
32+ rect rgba(120, 120, 120, 0.08)
33+ Note over User,AS: Front channel (browser)
34+ Client-->>User: 302 Found → /authorize
35+ User->>AS: GET /authorize (code_challenge)
36+ Note over User,AS: The user logs in and approves
37+ AS-->>User: 302 Found → redirect_uri?code=…
38+ User->>Client: GET redirect_uri?code=…
39+ end
40+ rect rgba(120, 120, 120, 0.08)
41+ Note over Client,RS: Back channel (server to server)
42+ Client->>AS: POST /token (code, code_verifier)
43+ AS-->>Client: 200 OK + access token
44+ Client->>RS: GET /api (bearer token)
45+ RS-->>Client: 200 OK + resource
46+ end
47+
48+ 1. The client redirects the browser to the authorization endpoint.
49+ 2. The request contains ``code_challenge `` and ``code_challenge_method ``.
50+ With ``S256 ``, ``code_challenge `` is the SHA-256 hash of
51+ ``code_verifier ``, in base64url. :class: `CodeChallenge ` checks the format
52+ of ``code_challenge `` and the support of ``code_challenge_method ``. The
53+ ``save_authorization_code `` method of the grant stores them with the code.
54+ 3. The authorization server redirects the browser to the client with a code.
55+ 4. The client receives the code.
56+ 5. The client sends the ``code `` and the ``code_verifier ``.
57+ :class: `CodeChallenge ` computes the challenge from ``code_verifier `` and
58+ compares it with the stored ``code_challenge ``. It returns
59+ ``invalid_grant `` if they differ.
60+ 6. The authorization server returns an access token.
61+ 7. The client calls the API of the Resource Server with the access token,
62+ in the ``Authorization: Bearer `` header.
63+ 8. The Resource Server returns the protected resource.
64+
65+ The ``/authorize ``, ``/token `` and ``/api `` paths are examples.
66+
1567.. module :: authlib.oauth2.rfc7636
1668
1769
0 commit comments