Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 39 ยท Tokens, JWT and OAuth

OAuth 2.0 Flows and PKCE

Understand OAuth 2.0 roles, the authorization code flow with PKCE, client credentials and scopes, and run working simulators of each flow in Node.js.

OAuth 2.0 answers one question: how can a user let an application use their data on another service without giving that application their password? When a photo-printing site asks to read your pictures from a cloud drive, you log in at the drive's own page, approve a list of permissions, and the printing site receives a token that works only for those permissions. You never typed your password into the printing site, and you can revoke its access later.

OAuth is a framework for delegated authorization. It does not say who the user is (that is OpenID Connect, the next lesson), it only says what an application may do. The real flows need a browser and a real identity provider, so the flows below are described read-only, with runnable simulators in the same process that show every message and check.

The four roles

Resource owner The user who owns the data.
Client The app that wants access.
Authorization server Logs in the user, issues tokens.
Resource server Your API that checks tokens.

The authorization server and the API are often the same company.

1 / 2

Key terms

Term Meaning
Client ID / secret Identifies the application (the secret only exists for confidential clients such as servers)
Redirect URI The exact URL the server may send the user back to; must be pre-registered
Scope A named permission, such as notes:read or notes:write
Authorization code A one-time, short-lived code that proves the user approved
Access token What the client sends to the API
state A random value the client checks on return, to stop CSRF

Authorization code flow

This is the flow for any app with a user. The user's browser is sent to the authorization server, approves, and comes back with a short-lived code. The client then exchanges the code for tokens on a direct (back-channel) request, so the tokens never pass through the browser's address bar.

sequenceDiagram
    participant U as User (browser)
    participant C as Client app
    participant A as Authorization server
    participant R as Resource API
    C->>U: Redirect to /authorize (client_id, scope, state, code_challenge)
    U->>A: Login and approve scopes
    A->>U: Redirect to redirect_uri?code=...&state=...
    U->>C: Browser delivers code and state
    C->>A: POST /token (code, code_verifier, client_id)
    A->>C: access_token, refresh_token
    C->>R: GET /notes with Bearer access_token
    R->>C: 200 data

The code travels through the browser, the tokens travel directly between servers.

PKCE

Anyone who intercepts the code (a malicious app registered for the same custom URL scheme, a leaky log) could exchange it. PKCE (Proof Key for Code Exchange, "pixie") stops that. Before starting, the client creates a random secret called the code_verifier, and sends only its hash, the code_challenge, in the first request. When exchanging the code it sends the original verifier. The server hashes it and compares. A thief who only saw the code does not know the verifier.

PKCE is required for public clients (SPAs, mobile apps, which cannot keep a secret) and recommended for every client.

Node.js Authorization code flow with PKCE

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Three checks protect this flow: the exact redirect URI match (never prefix or wildcard matching), the state comparison on return, and the PKCE verifier. A real server also expires the code after about a minute.

Client credentials flow

When there is no user, for example a nightly job calling another service, the client authenticates as itself. It sends its ID and secret to the token endpoint and receives an access token for its granted scopes. The secret must live only in a server environment, never in a browser or mobile app.

Node.js Client credentials and scopes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the two different error statuses: 401 means "I do not know who you are", 403 with insufficient_scope means "I know you, but this token lacks the permission".

Other flows and what to avoid

  • Device code: a TV or command-line tool shows a short code, the user types it on a phone, and the device polls the token endpoint. Use it where entering a password is awkward.
  • Refresh token grant: exchanges a refresh token for a new access token, as in Access Tokens and Refresh Tokens.
  • Implicit flow (tokens in the URL fragment) and the resource owner password grant (the app collects the user's password) are deprecated. Use authorization code with PKCE instead.

Scopes in your API

Define scopes around what a client may do, such as notes:read and notes:write, not around who the user is. Your API checks the scope on each route, and also checks the user's own permissions: a token with notes:read still must not read someone else's notes (see Authorization and Object-Level Access).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is OAuth 2.0 mainly for?

    OAuth delegates limited access through tokens, so the app never sees the user's credentials.
  2. 2. What does PKCE protect against?

    The token request must include the verifier whose hash was sent at the start, which an interceptor of the code does not have.
  3. 3. Which flow fits a nightly job that calls an API with no user involved?

    Client credentials authenticates the application itself with its ID and secret.
  4. 4. What is the state parameter for?

    The client stores a random value, sends it, and checks that the same value returns on the redirect.
  5. 5. A valid token lacks the required scope for a route. Which response is right?

    The caller is identified but not permitted, which is 403. 401 is for missing or invalid credentials.

Summary

  • OAuth 2.0 delegates access: the client gets a token for specific scopes, and never the user's password.
  • Use authorization code with PKCE for apps with users, client credentials for machine-to-machine calls, and device code for input-limited devices.
  • Always match the redirect URI exactly, check state, and send a PKCE challenge and verifier.
  • Authorization codes are single-use and short-lived; tokens are exchanged on a back channel.
  • Answer missing credentials with 401 and missing scope with 403.

Next: OpenID Connect: Logging In with OAuth