Skip to content

Commit 1996c56

Browse files
committed
docs: PKCE flow chart illustration
1 parent e4c8620 commit 1996c56

3 files changed

Lines changed: 54 additions & 2 deletions

File tree

‎docs/oauth2/specs/rfc7523.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ type. For instance, with the authorization code grant:
130130

131131
sequenceDiagram
132132
autonumber
133-
participant User as User agent
133+
participant User as User's browser<br/>(User Agent)
134134
participant Client
135135
box rgba(80, 120, 220, 0.12) JWTBearerClientAssertion
136136
participant AS as Authorization Server

‎docs/oauth2/specs/rfc7636.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,58 @@ This :rfc:`7636` is used to improve the security of Authorization Code flow
1212
for public clients by sending extra "code_challenge" and "code_verifier"
1313
to 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

‎docs/oauth2/specs/rfc8628.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ endpoint, while the user approves the request in a browser on another device:
2222
sequenceDiagram
2323
autonumber
2424
participant Device as Client (device)
25-
participant User as User (browser)
25+
participant User as User's browser<br/>(User Agent)
2626
participant AS as Authorization Server
2727
participant RS as Resource Server
2828

0 commit comments

Comments
 (0)