atprotocol-oauth-authorization-flow.mermaid
edited
1sequenceDiagram
2 participant PLC as PLC / DID Host
3 participant ID as Identity / Handle Resolution
4 participant Client as Client App
5 participant User as User/Browser
6 participant AS as Authorization Server<br/>(PDS/Entryway)
7 participant CIMD as CIMD Document
8 participant RS as Resource Server<br/>(PDS)
9
10 Note over ID: Typically over DNS or HTTP, but could<br/>also be a caching server like slingshot.
11
12 Note over Client,RS: 1. Identity Resolution Phase
13 Client->>Client: Start with Handle/DID<br/>or Server URL
14 Client->>ID: Resolve Handle → DID
15 ID->>Client:
16 Client->>PLC: Fetch DID Document
17 PLC->>Client: Retrieve PDS Service from DID Document
18 Client->>RS: Fetch OAuth Protected<br/>Resource Metadata<br>from PDS Service
19 RS->>Client: Retrieve Authorization<br/>Server URL
20 Client->>AS: Fetch Authorization<br/>Server Metadata
21
22 Note over Client,RS: 2. Authorization Request (PAR)
23 Client->>Client: Generate PKCE code_verifier<br/>& code_challenge
24 Client->>Client: Generate DPoP keypair<br/>& state token
25 Client->>AS: POST PAR with:<br/>- code_challenge<br/>- scopes (atproto)<br/>- redirect_uri<br/>- login_hint (optional)<br/>- client_assertion (confidential)
26 AS-->>Client: Error: DPoP nonce required
27 Client->>AS: Retry PAR with DPoP nonce
28 AS-->>Client: Returns request_uri
29
30 Note over Client,RS: 3. User Authorization
31 Client->>User: Redirect to Authorization<br/>Endpoint with request_uri
32 AS->>AS: Authenticate User
33 AS->>CIMD: Fetch Client ID<br>Metadata Document
34 CIMD->>AS:
35 User->>AS: Approve
36 AS->>User: Redirect to redirect_uri<br/>with code, state, iss
37 Note over AS: OR
38 User->>AS: Deny
39 AS->>User: Redirect if redirect_uri is<br>valid for client<br>with error=access_denied
40
41 Note over Client,RS: 4. Token Request, unless error parameter
42 User->>Client: Callback with code
43 Client->>Client: Verify state matches
44 Client->>Client: Verify iss matches AS URL
45 Client->>AS: POST Token Request:
46 Note over Client,AS: Sends:<br>- code<br/>- code_verifier (PKCE)<br/>- DPoP proof<br/>- client_assertion (confidential)
47 AS-->>Client: Token Response
48 Note over AS,Client: Returns:<br/>- access_token<br/>- refresh_token<br/>- sub (DID)<br>-Expiry Info
49 Client->>Client: Verify sub DID matches<br/>expected account DID
50
51 Note over Client,RS: 5. Resource Access
52 Client->>RS: Request Resource with:<br/>- DPoP proof (with auth)<br/>- access_token
53 RS-->>Client: Error: DPoP nonce required
54 Client->>RS: Retry with DPoP nonce
55 RS-->>Client: Returns Resource
56
57 Note over Client,RS: 6. Token Refresh (when expired, or near expiring)
58 Client->>AS: POST Token Refresh
59 Note over Client,AS: Sends:<br/>- refresh_token<br/>- DPoP proof<br/>- client_assertion (confidential)
60 AS-->>Client: Returns new tokens