An email arrives at the Aroma Store team. CataBox, a third-party application that helps coffee enthusiasts keep a tasting notebook, wants to offer its users the ability to import automatically the coffees they have bought from Aroma. The technical request is simple: "can we read one of your customers' orders?".

With the authentication we built in 03-06 there is only one possible answer, and it is a bad one: that the customer gives CataBox their Aroma Store email address and password, and that CataBox calls POST /v1/sessions pretending to be them. That means a company you do not control is storing your customers' passwords, that the token it obtains has every permission — including creating orders and changing the delivery address — that you cannot revoke its access without forcing the customer to change their password, and that you have no way of telling which requests come from the customer and which from CataBox.

OAuth 2.0 exists for exactly this. This lesson explains what problem it solves, how it is put together, which flows are used today and which are discouraged, how OpenID Connect adds the piece it lacks on top — identity — and how a token from an external authorisation server is validated in our API. By the end, src/middleware/oauth-authentication.js will exist and will coexist with authenticate from 03-06.

Warning. OAuth 2.0 is a security protocol and its details matter: one badly validated parameter turns a correct flow into an account takeover. The code in this lesson is didactic and must be reviewed by a security professional before any real deployment. All the data, domains and credentials are fictional.

1. The problem: delegating access without sharing credentials
2. The four roles of OAuth 2.0
3. Tokens: access, refresh and scopes
4. Opaque tokens versus JWTs: introspection or local validation
5. Authorization Code + PKCE
6. Why the implicit and password flows are discouraged
7. Client Credentials: SwiftShip, machine to machine
8. Refresh Token and Device Code
9. state, CSRF and the authorisation request's parameters
10. OpenID Connect: identity on top of OAuth
11. Validating the token in the API: JWKS, kid and the claims
12. The authenticateOAuth middleware and its coexistence with authenticate
13. Scopes and roles combined
14. Client registration, secrets and redirect_uri
15. Revocation and logout
16. Why you should not implement your own authorisation server
17. OAuth errors and their translation into the Aroma catalogue

Before OAuth, the usual pattern was called the shared password antipattern, and it looked like this:

The central idea of OAuth 2.0 fits in one sentence: the client never sees the credentials; the user authenticates at a trusted site and what comes back is a bounded, revocable permission.

And one clarification that avoids 90% of the initial confusion: OAuth 2.0 is a delegated authorisation protocol, not an authentication one. It is not there for "sign in with", however much it gets used that way everywhere. What is there for that is OpenID Connect, which is built on top of it (section 10).

The most important practical consequence for this course: our API is only the resource server. It shows no login screens, manages no passwords, issues no tokens and knows nothing about consent. Its only job in OAuth is:

1. Receive an Authorization: Bearer <token>.
2. Verify that the token is genuine, current and addressed to it.
3. Extract who the subject is and which scopes they have.
4. Decide whether that combination may do what it is asking for.

That is all. Nothing else in this lesson is implemented inside our API, and that separation is precisely the protocol's value.

Notice step 5: the API does not ask the authorisation server on every request. It downloads its public keys once, caches them and verifies locally. Why, in section 4.

The reason there are two is a compromise between security and usability: you want the token that travels constantly over the network to expire soon, but you do not want to ask the user for their password every fifteen minutes. The refresh token travels rarely, is stored better and can be revoked centrally.

This architecture is the same one we already built by hand in 03-06 with our own access and refresh tokens. The difference is who issues them: there our API did; here a specialised authorisation server does, and our API only verifies them.

A scope is a label that bounds what a token allows. Scopes are requested in the authorisation request, the user sees them on the consent screen, and they travel inside the token.

Aroma Store's scopes:

Four scope design rules that avoid most of the problems:

1. resource.action granularity, not one scope per endpoint. With 24 URIs, one scope per endpoint produces an unreadable consent screen.
2. Always separate read from write. CataBox asks for orders.read and never orders.write. That separation is 80% of the value.
3. A scope bounds, it does not grant. A token having orders.read does not mean it can read all orders: it means it can read the orders of the token's subject. The ownership check (BOLA, 04-02) is still mandatory.
4. Write the text the user will see alongside the scope. If you cannot explain it in one comprehensible line, the scope is badly designed.

The access token can be one of two natures, and the choice directly affects how our API validates it.

Introspection (RFC 7662) looks like this:

The decisive field is active: if it is false, the token is worthless, with no further explanation.

What Aroma Store chooses: JWTs with local validation, for three reasons. Latency matters (one extra call per request doubles the catalogue's response time); availability matters (if the AS goes down, with introspection the whole API goes down with it); and we get immediate revocation another way, with short-lived tokens (15 minutes) and refresh token revocation.

The trade-off: a revoked JWT access token remains valid until it expires. If that is unacceptable for some operation — cancelling an order, changing a password — introspection is used for those operations only, or a revocation list in Redis is consulted. It is a per-endpoint decision, not a global one.

And a reminder that never hurts: a JWT is signed, not encrypted. Anyone who intercepts the token reads its content with a Base64 decoder. Never put sensitive data in the claims.

This is the flow. If you remember only one thing from this lesson, make it this: it works for SPAs, for mobile applications, for server applications and for third-party applications such as CataBox.

PKCE (Proof Key for Code Exchange, pronounced "pixy") is the extension that makes it secure for clients that cannot keep a secret. It is now considered mandatory for all clients, confidential ones included.

Let us look at the real requests.

Steps 3-4: the authorisation request. It happens in the user's browser, not on CataBox's server:

Step 9: the redirect back. The code arrives in the URL, and it is single-use with a very short life (typically 30–60 seconds):

Step 11: exchanging the code for the token. This is a server-to-server request (or one from the app), never a redirect:

The authorisation code travels through the browser's URL, and that is not a secure channel: it stays in the history, it can appear in a proxy's logs and, on mobile, another application can register the same URI scheme and steal the redirect. Before PKCE, an attacker who captured the code could exchange it for a token, because the AS had no way of knowing that whoever was exchanging it was not whoever had requested it.

PKCE binds the two requests with a single-use secret:

The cryptographic property that makes it work: SHA-256 cannot be reversed. An attacker who sees the code_challenge in the URL cannot deduce the code_verifier, so even if they steal the code they cannot exchange it. And code_challenge_method must always be S256; the value plain exists for compatibility and protects against nothing.

You will find them in old tutorials. The current OAuth 2.0 best practices (and OAuth 2.1) retire them.

The password flow deserves a nuance because it raises legitimate questions: it was created for first-party applications, that is, your own. But even there it is a bad idea, because your own app ends up handling passwords, cannot go through a second factor and benefits from none of the AS's infrastructure. The Aroma Store SPA and Aroma Mobile use Authorization Code + PKCE just like CataBox, even though they are ours. The difference between a first-party and a third-party app is that the first-party one can skip the consent screen, not that it uses a different flow.

When no user is involved, there is nobody to ask for consent. SwiftShip is a system that acts in its own name to mark orders as shipped.

Three characteristics distinguish it:

• There is no redirect_uri, no code and no consent: only the client and its secret.
• There is no refresh token: when the access token expires, another is requested. It is cheap because it requires nobody in front of a screen.
• The token's sub is the client itself (swiftship), not a person. In our API that corresponds to the partner role, and it means that the per-customer ownership checks do not apply: authorisation has to come from somewhere else (which orders SwiftShip may touch and in which states).

A client using this flow is confidential by definition: it keeps a secret on a server. It is never used in a SPA or in a mobile app, because anyone can extract the secret from the downloaded code.

The response is a new access token and, in modern implementations, a new refresh token as well. That is called refresh token rotation and it is an important defence: if a refresh token is used twice, the AS knows that one of the two uses is an attacker's — because the legitimate one already received its replacement — and revokes the whole token family, closing the session. That is reuse detection, and it is worth demanding when choosing a provider.

Where the refresh token is stored, by type of client:

For SPAs, the current recommendation is the BFF pattern (Backend For Frontend): a small backend of your own holds the tokens and the SPA talks to it using a session cookie. If that is not viable, use rotating refresh tokens with a short life and never localStorage.

For devices with no keyboard and no browser — a screen in the coffee shop showing the stock, a television. The device asks for a code, shows the user "go to aromastore.example/activate and enter KDLF-9XZQ", and meanwhile polls the AS until the user completes the authorisation on their phone. It is mentioned for completeness; it does not apply to Aroma Store's current consumers.

Which attack state prevents. Without it, an attacker starts the flow with their Aroma Store account, captures the code from the redirect and tricks the victim into having their browser visit https://catabox.example/callback?code=<the attacker's>. CataBox exchanges that code and associates the attacker's Aroma Store account with the victim's CataBox session. From then on, everything the victim saves in CataBox goes into an account the attacker controls.

The defence is a random value bound to the browser session:

With PKCE properly implemented the risk drops a great deal, but state is still mandatory: it protects against a different attack (fixation of the client's session, not code theft) and it also serves to remember where to return to inside the application.

OAuth 2.0 answers "may this application do this?". It does not answer "who is the user?". Using an access token as proof of identity is a classic and dangerous mistake: the token says nothing verifiable about who obtained it or which application it was issued for, and that is why token substitution attacks existed.

OpenID Connect (OIDC) is a thin, standardised layer on top of OAuth 2.0 that adds exactly what is missing.

Adding openid to scope is enough to turn the flow into OIDC:

The decoded id_token:

The most used standard claims:

Two warnings that cause real bugs:

• The user's key is sub, never email. An email address can be changed, can be reassigned and can arrive unverified. Linking accounts by email address is a route to account takeover if email_verified is false.
• The id_token is for the client, not for the API. It is not sent in Authorization: Bearer to the resource server. Our API validates the access token; the id_token is consumed by CataBox to know who it has connected.

The /userinfo endpoint completes the picture: it is called with the access token and returns up-to-date profile claims. It is used when the id_token was issued a while ago or when you prefer not to fatten it.

And the discovery document, which saves you configuring URLs by hand:

That is where jwks_uri comes from, which is the only thing our API needs.

Here our code finally comes in. We saw the mechanics of JWTs back in 03-06; what is new is two things: the signature is asymmetric (the AS signs with its private key, we verify with its public key) and the public key is discovered dynamically through JWKS.

JWKS (JSON Web Key Set) is a public document containing the issuer's verification keys:

Having two keys at once is not a mistake: it is rotation. The AS starts signing with aroma-2026-08 while the tokens signed with aroma-2026-05 remain current until they expire. Each JWT's header says which one to use:

This natively solves the secret rotation problem we raised in 04-02: nothing has to be redeployed, the API discovers the new key by itself.

jose is the de facto standard library for JOSE/JWT in Node: it implements the JWKS cache, rotation and the standard's checks.

The claims that have to be verified, and what happens if you skip one:

aud is the most forgotten and one of the most serious. If a user has a token for another application from the same authorisation server and your API does not check aud, that token opens your API.

About clock skew: exp and nbf are absolute instants. If your server's clock is thirty seconds fast, you will reject freshly issued tokens with an incomprehensible token_expired. Hence clockTolerance, and hence servers running NTP. A reasonable tolerance is 30–60 seconds; more than that starts to become a risk.

About the key cache: without it you would make an HTTP request to the AS for every incoming request, which would throw away the advantage of local validation and create a hard dependency. With it, the AS can be down for ten minutes without your API failing to authenticate anybody.

You do not have to choose all at once. During the migration, the two mechanisms coexist: our own tokens from 03-06 (HS256, issued by our API) and the OAuth ones (RS256, issued by the AS). A selector middleware decides based on the token's header:

The comment in the code points at what matters: the token's header is untrusted input. It is used only to decide which verifier takes the request; that verifier then imposes algorithms: ['RS256'] or ['HS256'] as appropriate, so an attacker gains nothing by lying in alg.

Position in the chain. It does not change from 03-06: authentication is still the first thing inside each route, not in src/app.js. The route chain's order becomes:

And src/app.js is untouched in this lesson: OAuth adds no global middleware.

There is a frequent confusion here worth clearing up precisely, because they are two mechanisms answering different questions:

Effective authorisation is the intersection of the two. A token with reviews.moderate whose subject is a customer cannot moderate: the scope says what the application asked for, but the role says what the person can do. And the other way round: an administrator using CataBox, which only asked for orders.read, cannot moderate reviews from CataBox even though her role would allow it in the back office.

And a compatibility rule for the coexistence: an own token from 03-06 carries no scope. So that requireScope does not break the existing routes, authenticateOwn fills scopes with the complete set corresponding to the role; that is, a first-party token behaves as if the user had consented to everything. It is coherent, because in that flow the user is using our own application directly.

Before CataBox can ask for anything, it registers at the authorisation server and obtains:

Confidential versus public:

A very repeated mistake: embedding the client_secret in a SPA or a mobile app. Anything downloaded to the user's device is public, however obfuscated or compiled it is. That is the exact reason PKCE exists.

The redirect_uri is compared byte for byte. Not by prefix, not by wildcard, not ignoring the fragment. An AS that accepts https://catabox.example/* lets an attacker who controls any path on that domain (a profile page with uploaded content, say) receive the authorisation codes. The rules: HTTPS mandatory, no wildcards, no dynamic parameters — whatever you need to remember goes in state — and on mobile, custom schemes or verified App Links rather than a scheme any app can register.

Token revocation (RFC 7009):

It answers 200 even if the token did not exist, deliberately: that way the endpoint cannot be used to find out whether a token is valid.

What to revoke and what effect it has:

Logout. There are three levels here that are worth not confusing, because the user thinks "log out" is a single thing:

1. Local: the application deletes its tokens. The user still has an open session at the AS.
2. RP-Initiated Logout (OIDC): the application redirects to end_session_endpoint and the AS closes its session too.
3. Back-Channel Logout: the AS notifies every connected application behind the scenes so that they close the session. This is what a real single sign-on scenario needs.

In the Aroma Store SPA, "log out" must be at least level 2; if you only do level 1, pressing "sign in" again puts the user straight back in without asking for anything, and on a shared computer that is a security problem.

You will have guessed it while reading the lesson: implementing a correct OAuth 2.0 authorisation server is a project in itself, and doing it badly does not produce a visible failure, it produces a silent vulnerability.

What has to be built and maintained correctly:

• Issuing and validating single-use codes, short-lived and bound to the client.
• PKCE with S256, exact redirect_uri comparison, state and nonce validation.
• Asymmetric signing, JWKS publication and key rotation without cutting off the service.
• Refresh token rotation with reuse detection and cascading revocation.
• Consent screens, a record of consents and their withdrawal.
• Password management, second factor, account recovery, lockout after failed attempts.
• Discovery, introspection, revocation and userinfo endpoints.
• Keeping up with updates to the standard and with security advisories.

On top of that, your authorisation server is the system's most critical asset: whoever compromises it compromises everything.

Aroma Store's decision: a managed provider at auth.aromastore.example. Our API remains solely a resource server, which is exactly the role we have implemented.

And a useful clarification: this does not invalidate the work from 03-06. Own tokens remain perfectly reasonable for the first-party case — your SPA talking to your API, with no third parties. OAuth comes in when a third party appears, when you need federated login or when several APIs share an identity.

OAuth defines its own error codes, in this shape:

That format is emitted by the authorisation server, not by our API. The errors a CataBox client sees break down like this:

Our API keeps its own format in the body and uses the WWW-Authenticate header to speak OAuth's language, which is what RFC 6750 expects:

That way both things hold at once: the catalogue's consistency towards our consumers (04-01) and interoperability with generic OAuth libraries, which read WWW-Authenticate to decide whether they should refresh the token or ask for more permissions. There is no need to extend the error catalogue: not_authenticated, token_expired, insufficient_permissions and service_unavailable cover every case the resource server emits.

Using the access token as proof of identity. The access token is for the API; identity comes from OIDC's id_token. Confusing them opens the door to token substitution attacks.

Not validating aud. A token issued for another application from the same issuer would open your API. It is the most forgotten check.

Accepting any algorithm. Without an allowlist, alg:none and RS/HS confusion are exploitable. Pin ['RS256'].

Storing tokens in localStorage. Any XSS steals them. An HttpOnly cookie with a BFF, or the system keychain on mobile.

Embedding a client_secret in a SPA or mobile app. It is public by definition. Public client + PKCE.

Accepting a redirect_uri with wildcards. A single controllable path on your domain turns into code theft.

Skipping state because "we already use PKCE". They protect against different attacks. Both, always.

Asking for every scope "just in case". It lowers conversion — the user sees an alarming screen — and increases the damage of a breach. Ask for the minimum and extend when you need to.

Tip: start from the discovery document. /.well-known/openid-configuration gives you every URL. Configuring token_endpoint by hand is a source of silly mistakes.

Tip: test expiry for real. Configure a test AS with 30-second tokens and check that your client refreshes on its own and that your API answers token_expired with the right WWW-Authenticate.

Tip: log the client_id. Knowing that a wave of 429s comes from CataBox and not from your SPA changes the diagnosis completely. We will see this in 04-07.

For each Aroma Store consumer, state the correct flow, the client type and the minimum scopes. Justify each choice.

1. The shop's SPA (https://aromastore.example), which allows buying and reviewing.
2. The Aroma Mobile app, with the same functions.
3. SwiftShip's backend, which marks orders as shipped.
4. CataBox, which imports the user's purchase history.
5. An internal nightly script that exports sales statistics.

This middleware has been proposed for validating OAuth tokens. Find at least four security flaws and fix them.

Aroma Store is going to let third-party applications manage a customer's monthly coffee subscription: view it, pause it, resume it and change the variety. Design the necessary scopes, the consent text for each one, and decide which combination of role and scope each endpoint requires.

Solution 1

Justifications:

• 1 and 2 are public even though they are ours: the code is downloaded to the device and cannot keep a secret. And they use Authorization Code + PKCE, not the password flow, so they can go through 2FA and never handle passwords.
• 3 and 5 have no user present, so Client Credentials. The sub is the machine itself and there is no consent.
• 4 is confidential because the exchange happens on its server, but it uses PKCE all the same: the current recommendation is to apply it always. It asks only for orders.read; if it asked for orders.write the registration should be refused, because it does not need it for its use case.
• Case 5 requires extending the scope catalogue with sales.read, and it is worth noting explicitly: scopes, like error codes, are part of the contract and are documented in openapi.yaml.

Solution 2

Flaws:

1. It validates neither iss nor aud: it accepts tokens from any issuer and tokens issued for any other API.
2. It does not pin algorithms: vulnerable to alg:none and to RS/HS confusion.
3. ?? keys[0]: if the kid matches no key, it uses the first one "and hopes for the best". An unknown kid must be a rejection.
4. It downloads the JWKS on every request: added latency, a hard dependency on the AS and a denial-of-service vector (all it takes is sending tokens with made-up kids).
5. id: payload.email: the stable identifier is sub. An email address can change or arrive unverified.
6. scopes: payload.scope leaves a string where a set is expected; .has() would fail or, worse, .includes() would produce false positives (orders.read "includes" orders.rea).
7. No try/catch: if the header is missing or the token is malformed, the split or the JSON.parse throws a TypeError and it ends up as a 500 instead of a 401 — and with no WWW-Authenticate.

The fix is the middleware from section 12: createRemoteJWKSet with a cache for 3 and 4, jwtVerify with issuer, audience and algorithms for 1 and 2, payload.sub for 5, a Set for 6 and the try/catch with error translation for 7.

Solution 3

Scopes:

Deliberately, a scope per action is not created (subscriptions.pause, subscriptions.resume…): it would produce an unreadable consent screen and none of those actions has a risk profile different from the others. Nor is orders.write reused, because an application that manages subscriptions must not be able to create one-off orders: mixing the two would extend the permission beyond what is needed.

Endpoints:

Two final observations. requireRole('customer', ...) is not enough to stop a customer pausing somebody else's subscription: that is a BOLA and it is checked in the service, as we saw in 04-02. And the actions are modelled as noun subresources (/pause, /resumption) rather than verbs, consistently with 02-02 and with the antipatterns from 04-01.

OAuth 2.0 solves a very concrete problem that the authentication from 03-06 could not: letting a third-party application access a user's data without knowing their password, with bounded permissions, expiry and revocation. You have seen the four roles and, above all, that our API is only the resource server: it receives a token, verifies it and decides; nothing more. You know the difference between an access token and a refresh token, the scopes designed for Aroma Store and why reading is always separated from writing; the choice between an opaque token with introspection and a JWT with local validation, with its explicit trade-off on revocation; the Authorization Code + PKCE flow with the detail of exactly which attack the code_verifier prevents, why the implicit and password flows are retired, Client Credentials for SwiftShip and refresh token rotation with reuse detection. You have seen that OpenID Connect is the layer that answers "who is it" with the id_token, sub as the stable key and /userinfo for the profile. And in the project you now have src/config/oauth.js and src/middleware/oauth-authentication.js, with verification by JWKS and kid — which incidentally solves key rotation — full validation of iss, aud, exp, nbf and algorithm, a key cache, clock tolerance, the new requireScope and a selector that lets our own tokens coexist with the OAuth ones.

You now know who is calling and what they can do. What is missing is how much they can call. In 04-04, Rate Limiting and Throttling, we will impose limits: we will see why every public API needs them — abuse, catalogue scraping, badly programmed client loops, cost and fairness — the difference between limiting, throttling and quotas, and the four classic algorithms with a comparison, including a token bucket implemented and commented. We will decide what is used as the key (IP, with the NAT problem and X-Forwarded-For; the authenticated customer; the OAuth client_id) and with which tiers for anonymous users, customers, SwiftShip and the back office; we will build src/middleware/rate-limit.js with express-rate-limit and its position in src/app.js, with a Redis store for multiple instances; we will return the 429 with Retry-After and the Aroma-RateLimit-* headers; and we will see what a well-behaved client should do with its exponential backoff and its jitter.