Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 39 ยท Projects and Practice

Project: A Mini OAuth 2.0 Provider

Build a miniature OAuth 2.0 authorization server with PKCE, RS256 access tokens, a JWKS endpoint and a resource API that enforces scopes, then attack it.

OAuth is easy to use and hard to implement correctly, which is why you should almost always use an existing identity provider in production. But building a miniature one is the best way to understand what those providers do for you, and what every check is for.

In this project you create three cooperating parts in one Node.js program: an authorization server (authorize and token endpoints, a JWKS endpoint), a resource server (a photos API that verifies tokens and enforces scopes), and a client that runs the authorization code flow with PKCE. Then you attack your own system and watch each defense stop the attack. It builds on OAuth 2.0 Flows and PKCE, OpenID Connect and JWT Pitfalls.

The three parts

Authorization server /authorize, /token, /jwks.json
Resource server /photos, checks token and scope.
Client Runs the code flow with PKCE.

Real systems split these across companies.

1 / 2

The plan

Endpoint Purpose
GET /authorize Validates the request, (pretends the user logged in and consented), redirects back with a code
POST /token Exchanges a code (with the PKCE verifier) or a refresh token for tokens
GET /jwks.json Publishes the public signing key
GET /photos Resource API: needs scope photos:read
POST /photos Resource API: needs scope photos:write

Choices to notice while reading the code:

  • Access tokens are RS256 JWTs: the authorization server signs with a private key; the resource server only ever sees the public key from the JWKS.
  • The redirect URI is compared exactly, and a request with an unknown client or redirect URI is never redirected (the server shows an error instead, so it cannot be used as an open redirector).
  • Authorization codes live 60 seconds, work once and are bound to the client, redirect URI and PKCE challenge.
  • Refresh tokens rotate; the resource server pins the algorithm and checks iss, aud, exp and the scope.
  • The "user" is fixed (ana). A real server would render a login and consent page here.

Build and run the whole system

Node.js Authorization server, resource server and client

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.

Every attack ends in a clear refusal. Walk through them one at a time and match each to the check in the code that stopped it. For example, attack E fails because the signature covers the claims, attack G because the resource server pins RS256, and attack C because the verifier hash does not match the stored challenge.

A scope enforcement matrix

Scopes should be tested as a table: every route against every scope combination. The helper below is the same decision the resource server made, isolated so you can see the whole matrix at once. A test like this belongs in your suite (Testing REST APIs).

Node.js Test every route against every scope

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.

Extend the project

  1. Add a consent screen step: a pending authorization the user approves or denies, returning error=access_denied.
  2. Add a client_credentials grant for a machine client with its own scopes (OAuth 2.0 Flows).
  3. Add token introspection (POST /introspect) so the resource server can check opaque tokens.
  4. Add an ID token and a /userinfo endpoint, then validate the ID token with the nonce check (OpenID Connect).
  5. Add key rotation: publish two keys in the JWKS and sign new tokens with the second kid.
  6. Add token revocation (POST /revoke) and a denylist check in the resource server.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does /authorize refuse to redirect when the redirect_uri is not registered?

    Unregistered redirect targets would make the server an open redirector that leaks codes.
  2. 2. How does the resource server know which key verifies a token?

    The kid names the key, and the JWKS endpoint publishes the public keys by kid.
  3. 3. A token has scope photos:read only and calls POST /photos. What is the correct response?

    The token is valid but lacks the permission, which is 403 with the missing scope named.
  4. 4. What makes an edited scope claim fail?

    Changing the payload invalidates the signature, and only the authorization server holds the private key.
  5. 5. Why mark an authorization code as used even when the PKCE check fails afterwards?

    Single-use codes mean an attacker gets one attempt at most, and a leaked code is dead after the legitimate use.

Summary

  • An OAuth provider validates the client and exact redirect URI, issues one-time short-lived codes bound to a PKCE challenge, and exchanges them for tokens.
  • Access tokens signed with RS256 let the resource server verify them with a public key from the JWKS, without a shared secret.
  • The resource server pins the algorithm and checks signature, issuer, audience, expiry and scope; missing scope is 403.
  • Refresh tokens rotate and cannot be reused.
  • Testing your own system with attacks shows what each check is for.
  • In production, use an established identity provider instead of building your own.

Next: Practice: Security Review of a Vulnerable API