How OAuth 2.0 Works: The Valet Key Pattern

Scenario context

OAuth 2.0 is an authorization protocol. It lets a third-party app (like Spotify) access your resources (like Facebook Friends) without you giving it your Facebook password. It uses short-lived Access Tokens as scoped, revocable keys.

Before diving into the flow, it helps to understand why OAuth 2.0 was invented. Historically, if Spotify wanted to read your Facebook friends list it would ask for your…

This walkthrough focuses on Tokens, Scopes, and Why Passwords Are the Wrong Tool Here.

Before making a design choice, clarify:

• Before diving into the flow, it helps to understand why OAuth 2.0 was invented.
• Historically, if Spotify wanted to read your Facebook friends list it would ask for your Facebook username and password.
• That's catastrophic — Spotify now has full access to your account forever, and you can only revoke it by changing your password.

Concepts in play: api-security-oauth2, canary-deployments, graph-traversal-algorithms, system-design-hld-architectures

Stage 1 — The Valet Key Pattern: Access Without Passwords

• Your car has two keys: - Master Key: Opens doors, starts engine, opens trunk and glovebox.
• (Your Password.) - Valet Key: Starts the engine and unlocks only the door.
• (Access Token.) You hand the Valet Key to the parking attendant (Third-Party App).
• They park the car (do the job) but can't steal the contents of the trunk (access your private data).

Observable outcome: They park the car (do the job) but can't steal the contents of the trunk (access your private data).

Stage 2 — The Four Roles Every OAuth Flow Has

• The Client never sees your password.
• It only gets a token from the Authorization Server after you approve the request.

Observable outcome: It only gets a token from the Authorization Server after you approve the request.

Stage 3 — The Authorization Code Flow: Step by Step

• This is the most secure and most common grant type.
• Used whenever the Client is a server-side web app.
• The sequence diagram reveals the two-phase design that makes the Authorization Code flow secure.
• The first phase (steps 1–4) runs inside the user's browser: the Client redirects the user to the Auth Server, the Auth Server displays a consent screen, and on approval sends a short-lived Auth Code back through the bro…

sequenceDiagram
    participant U as User (Browser)
    participant C as Client (Spotify)
    participant AS as Auth Server (Facebook)
    participant RS as Resource Server (FB API)

    U->>C: "Login with Facebook"
    C->>AS: Redirect: GET /authorize?client_id=...&scope=email
    AS->>U: Show consent screen: "Spotify wants your email. Allow?"
    U->>AS: Clicks Allow
    AS->>C: Redirect back with ?code=AUTH_CODE
    Note over C,AS: Server-to-server  user never sees this
    C->>AS: POST /token {code, client_secret}
    AS->>C: {access_token, refresh_token, expires_in}
    C->>RS: GET /me/email  Authorization: Bearer ACCESS_TOKEN
    RS->>C: {email: "you@example.com"}

Observable outcome: The first phase (steps 1–4) runs inside the user's browser: the Client redirects the user to the Auth Server, the Auth Server displays a consent screen, and on approval sends a short-lived Auth Code back through the bro…

Stage 4 — The Authorization Code Flow at a Glance

• The sequence diagram above shows the actors .
• This flowchart shows the decision path — what happens at each fork and what can go wrong: The flowchart adds the decision branches and failure paths the sequence diagram omits.
• If the user denies on the consent screen, the flow terminates immediately with an access denied error redirected back to the app — no Auth Code is ever issued.
• If the server-side code exchange fails (the code is expired, already used, or the client secret is wrong), the app must restart the entire flow from step one with a freshly generated state nonce.

flowchart TD
    A([User clicks Login with Google]) --> B[App redirects browser to /authorize with client_id, scope, redirect_uri, state]
    B --> C[Google shows Consent Screen]
    C --> D{User approves?}
    D -- No --> E([Access Denied  redirect back with error])
    D -- Yes --> F[Google redirects back to app with short-lived Auth Code in URL]
    F --> G[App server POSTs Auth Code + client_secret to /token]
    G --> H{Code valid & not expired?}
    H -- No --> I([Token Error  app must restart flow])
    H -- Yes --> J[Google returns Access Token + Refresh Token + expires_in]
    J --> K[App calls protected API Authorization: Bearer ACCESS_TOKEN]
    K --> L([API returns protected user data])

Observable outcome: If the server-side code exchange fails (the code is expired, already used, or the client secret is wrong), the app must restart the entire flow from step one with a freshly generated state nonce.

Stage 5 — Deep Dive: Access Tokens, Refresh Tokens, and Scopes

• Scopes: Limiting What the Token Can Do When Spotify redirects you to Facebook, it requests specific scopes: The consent screen shows exactly what Spotify is asking for.
• The token is limited to those scopes — Spotify cannot suddenly read your photos.
• Token Lifetimes Refresh Without Re-Login The user stays "logged in" without re-approving.
• The Refresh Token itself is rotated on use in modern implementations (rotation prevents replay attacks).

GET /authorize?scope=email+read_friends

Client → POST /token { grant_type=refresh_token, refresh_token=... }
Auth Server → new Access Token

Observable outcome: The Refresh Token itself is rotated on use in modern implementations (rotation prevents replay attacks).

Stage 6 — Real-World Applications: Where You See OAuth 2.0 Every Day

• OAuth 2.0 is not an abstract protocol — it runs silently behind nearly every "Login with…" button you have ever clicked.
• "Login with Google" on any website.
• When you click that button, the website (Client) sends you to Google's Authorization Server.
• You see a consent screen ("This site wants to see your name and email address").

Observable outcome: You see a consent screen ("This site wants to see your name and email address").

End-to-end outcome

Before diving into the flow, it helps to understand why OAuth 2.0 was invented.

Alternatives considered

Decision Guide: Which OAuth Grant Type to Use

• Web app with server backend : Authorization Code flow.

Failure and degraded modes

Scenario | Grant Type | Why |

• Detection: PKCE (Proof Key for Code Exchange): Used for public clients (mobile apps, SPAs) that cannot safely store a client secret .
• User or operator impact: PKCE (Proof Key for Code Exchange): Used for public clients (mobile apps, SPAs) that cannot safely store a client secret .

OAuth 2.0 vs OpenID Connect

• Detection: OAuth 2.0 answers: "Can this app access this resource?" OpenID Connect (OIDC) adds: "Who is this user?" — it returns an ID Token (JWT) with the user's identity alongside the access token.
• User or operator impact: OAuth 2.0 answers: "Can this app access this resource?" OpenID Connect (OIDC) adds: "Who is this user?" — it returns an ID Token (JWT) with the user's identity alongside the access token.

Common Security Pitfalls

• Detection: Common Security Pitfalls
• User or operator impact: Common Security Pitfalls