Mermaid OAuth Flow Diagram Guide

# Mermaid OAuth Flow Diagram Guide

OAuth diagrams are easy to get wrong because several systems participate in one login: the browser, your application, the identity provider, token endpoints, APIs, and sometimes a refresh-token store. Mermaid is a good fit because you can keep the diagram beside the authentication docs and update it in the same pull request as code changes.

This guide shows practical Mermaid diagrams for OAuth 2.0 and OpenID Connect flows, including authorization code, PKCE, token exchange, API access, refresh tokens, and failure paths.

Why Use Mermaid for OAuth Documentation?

OAuth documentation needs precision. A vague box-and-arrow drawing can hide critical details such as where the authorization code is created, which backend exchanges it, and whether tokens ever reach the browser.

Mermaid helps because it is:

• Reviewable — engineers can review changed arrows and labels in a diff.
• Portable — diagrams work in Markdown docs, READMEs, developer portals, and architecture notes.
• Fast to update — when the auth flow changes, the diagram changes as text.
• Detailed enough — sequence diagrams can show redirects, token exchanges, and API calls in order.

For most OAuth docs, use a sequence diagram for the runtime flow and a flowchart for the high-level architecture.

Authorization Code Flow Sequence Diagram

The authorization code flow is the standard pattern for server-side web applications. The browser receives a short-lived code, but the backend performs the token exchange.

sequenceDiagram
    actor User
    participant Browser
    participant App as Web App
    participant IdP as Identity Provider
    participant API as Resource API

    User->>Browser: Click Sign in
    Browser->>App: GET /login
    App-->>Browser: Redirect to /authorize
    Browser->>IdP: Authorization request
    IdP-->>Browser: Login and consent page
    User->>IdP: Authenticate
    IdP-->>Browser: Redirect with authorization code
    Browser->>App: GET /callback?code=...
    App->>IdP: Exchange code for tokens
    IdP-->>App: ID token + access token
    App->>API: Request with access token
    API-->>App: Protected data
    App-->>Browser: Signed-in session

The key security point is that the backend exchanges the code. If your application is a confidential client, keep client secrets on the server and do not expose them in browser code.

OAuth PKCE Flow Diagram

Public clients such as single-page apps and mobile apps often use PKCE. The client creates a code verifier, sends a derived code challenge to the authorization server, and later proves possession of the verifier during token exchange.

sequenceDiagram
    actor User
    participant Client as SPA or Mobile App
    participant IdP as Authorization Server
    participant API as Resource API

    Client->>Client: Generate code verifier and challenge
    User->>Client: Start login
    Client->>IdP: /authorize with code_challenge
    IdP-->>User: Login and consent
    User->>IdP: Authenticate
    IdP-->>Client: Redirect with authorization code
    Client->>IdP: /token with code + code_verifier
    IdP-->>Client: Access token and ID token
    Client->>API: API request with access token
    API-->>Client: Protected response

Label both the code challenge and code verifier in the diagram. Those two terms are commonly confused during implementation reviews.

OpenID Connect Login Flow

OpenID Connect adds an ID token for authentication. OAuth authorizes access to resources; OpenID Connect tells the application who the user is.

flowchart TD
    Start["User starts sign-in"] --> Auth["Redirect to authorization endpoint"]
    Auth --> Login["Identity provider authenticates user"]
    Login --> Code["Authorization code returned"]
    Code --> Token["Application exchanges code"]
    Token --> ID["Validate ID token"]
    Token --> Access["Store or use access token"]
    ID --> Session["Create application session"]
    Access --> API["Call protected API"]

This high-level flowchart is useful for onboarding because it separates authentication from API authorization without showing every HTTP header.

Refresh Token Flow

Refresh tokens are sensitive. A diagram should show where they are stored and which component can use them.

sequenceDiagram
    participant App as Backend App
    participant Store as Secure Token Store
    participant IdP as Token Endpoint
    participant API as Resource API

    App->>Store: Read encrypted refresh token
    App->>IdP: POST /token grant_type=refresh_token
    IdP-->>App: New access token and optional refresh token
    App->>Store: Rotate stored refresh token
    App->>API: Call API with new access token
    API-->>App: Data

If refresh-token rotation is enabled, show the rotation step explicitly. It helps reviewers confirm that the old token is replaced and not reused indefinitely.

Show Failure and Expiration Paths

Authentication docs often show only the happy path. Add failure branches for expired sessions, denied consent, invalid state, and token exchange errors.

flowchart TD
    Callback["OAuth callback"] --> State{"State parameter valid?"}
    State -->|No| Reject["Reject request and log security event"]
    State -->|Yes| Exchange["Exchange code for tokens"]
    Exchange --> Result{"Token exchange successful?"}
    Result -->|No| Error["Show sign-in error"]
    Result -->|Yes| Validate["Validate issuer, audience, nonce, and expiry"]
    Validate --> Valid{"Token valid?"}
    Valid -->|No| Error
    Valid -->|Yes| Session["Create session"]

Failure diagrams are especially useful in security reviews because they show whether the application validates state, nonce, issuer, audience, and expiration before creating a session.

OAuth Diagram Checklist

Before publishing a Mermaid OAuth diagram, check that it answers these questions:

1. Which component starts the authorization request?
2. Does the browser receive tokens, or only an authorization code?
3. Which component exchanges the code at the token endpoint?
4. Where are access tokens and refresh tokens stored?
5. Is PKCE shown for public clients?
6. Are state and nonce validation included where relevant?
7. What happens when login, consent, token exchange, or validation fails?

Final Recommendation

Use Mermaid sequence diagrams for the detailed OAuth message order and Mermaid flowcharts for the conceptual overview. Keep labels precise, show token boundaries clearly, and include the failure paths that matter for security.

A good OAuth flow diagram is not just documentation for new developers. It is a review tool that helps teams catch unsafe assumptions before they become production authentication bugs.