PlantUML Sequence Diagram: OAuth2 Authentication Flow

OAuth2 Authentication Flow in PlantUML

Sequence diagrams are ideal for documenting OAuth2 flows because they clearly show the multi-party exchange between the user, client application, authorization server, and resource server.

Authorization Code Grant

@startuml
title OAuth2 Authorization Code Grant

actor User
participant "Client App" as Client
participant "Auth Server" as Auth
participant "Resource Server" as RS

User -> Client: Click "Login"
Client -> Auth: GET /authorize?response_type=code
Auth -> User: Show login page
User -> Auth: Enter credentials
Auth -> User: Authorization code (redirect)
User -> Client: Redirect with ?code=abc123
Client -> Auth: POST /token (code + client_secret)
Auth --> Client: Access token + Refresh token
Client -> RS: GET /api/data (Bearer token)
RS --> Client: Protected resource
Client --> User: Display data
@enduml

Key Elements

Participants: Each party in the OAuth flow gets its own lifeline. Using stereotypes like actor for the human user makes the diagram immediately readable.

Message Labels: Include the HTTP method and path in the label (e.g., POST /token) so readers can map the diagram directly to API calls.

Return Messages: Use dashed arrows (-->) for responses to visually distinguish them from requests.

Adding Notes

note right of Auth
  Validates client_id,
  client_secret, and
  authorization code
end note

Notes add context without cluttering the message flow. Place them on the side with the most space.

Grouping with Alt/Else

alt Token Valid
  RS --> Client: 200 OK + data
else Token Expired
  RS --> Client: 401 Unauthorized
  Client -> Auth: POST /token (refresh_token)
  Auth --> Client: New access token
end