Add example for Authorization Code grant.

authorization-code/README.md

@@ -0,0 +1,98 @@
+# Authorization Code Grant Example
+
+## Architecture
+
+The authorization code workflow is described in
+[RFC 6749, section 4.1](https://datatracker.ietf.org/doc/html/rfc6749.html#section-4.1):
+
+```
++----------+
+| Resource |
+|   Owner  |
+|          |
++----------+
+     ^
+     |
+    (B)
++----|-----+          Client Identifier      +---------------+
+|         -+----(A)-- & Redirection URI ---->|               |
+|  User-   |                                 | Authorization |
+|  Agent  -+----(B)-- User authenticates --->|     Server    |
+|          |                                 |               |
+|         -+----(C)-- Authorization Code ---<|               |
++-|----|---+                                 +---------------+
+  |    |                                         ^      v
+ (A)  (C)                                        |      |
+  |    |                                         |      |
+  ^    v                                         |      |
++---------+                                      |      |
+|         |>---(D)-- Authorization Code ---------'      |
+|  Client |          & Redirection URI                  |
+|         |                                             |
+|         |<---(E)----- Access Token -------------------'
++---------+       (w/ Optional Refresh Token)
+```
+
+### Provider dependencies
+
+- @node-oauth/express-oauth-server (uses @node-oauth/oauth2-server)
+- express
+- body-parser
+
+### Client dependencies
+
+- express
+- ejs
+
+## Installation and usage
+
+Install dependencies in both provider and client directories:
+
+```shell
+$ cd provider && npm install
+$ cd ../client && npm install
+```
+
+Create a `.env` file in the authorization-code directory:
+
+```
+CLIENT_ID=testclient
+CLIENT_SECRET=testsecret
+REDIRECT_URI=http://localhost:3000/callback
+USER_ID=user1
+USERNAME=demo
+PASSWORD=demo
+```
+
+Start the provider (authorization server + resource server):
+
+```shell
+$ cd provider && npm start
+```
+
+Start the client application:
+
+```shell
+$ cd client && npm start
+```
+
+Visit http://localhost:3000 to start the authorization code flow.
+
+## About This Example
+
+This example demonstrates a clear separation between the OAuth2 provider (authorization server + resource server) and the client application. Unlike other examples that might combine both roles in a single application, this example shows:
+
+- **Provider** (port 8080): Acts as both authorization server and resource server
+- **Client** (port 3000): A separate web application that consumes OAuth2 services
+
+This separation makes it easier to understand what the framework supports and what it doesn't.
+
+## Flow
+
+1. User visits the client application at http://localhost:3000
+2. User clicks "Login" to start the authorization flow
+3. User is redirected to the provider's authorization page
+4. User enters credentials and grants authorization
+5. User is redirected back to the client with an authorization code
+6. Client exchanges the code for an access token
+7. Client can now access protected resources using the access token

authorization-code/client/index.js

@@ -0,0 +1,76 @@
+require("dotenv").config({ path: "../.env" });
+const express = require("express");
+const crypto = require("crypto");
+
+const app = express();
+const states = new Map();
+
+app.set("view engine", "ejs");
+app.set("views", "./views");
+app.use(express.static("public"));
+
+const authServer = "http://localhost:8080";
+const clientId = process.env.CLIENT_ID || "testclient";
+const clientSecret = process.env.CLIENT_SECRET || "testsecret";
+const redirectUri =
+  process.env.REDIRECT_URI || "http://localhost:3000/callback";
+
+function generateState() {
+  return crypto.randomBytes(16).toString("hex");
+}
+
+app.use(express.urlencoded({ extended: false }));
+app.use(express.json());
+
+app.get("/", (req, res) => {
+  res.render("index", {
+    authServer: authServer,
+  });
+});
+
+app.get("/login", (req, res) => {
+  const state = generateState();
+  states.set(state, { created: Date.now() });
+
+  res.render("authorize", {
+    client: { id: clientId },
+    redirectUri: redirectUri,
+    scope: "read write",
+    state: state,
+    authServer: authServer,
+  });
+});
+
+app.get("/callback", (req, res) => {
+  const { code, state, error } = req.query;
+
+  if (error) {
+    return res.render("error", {
+      message: `Authorization Error: ${error}`,
+    });
+  }
+
+  if (!states.has(state)) {
+    return res.render("error", {
+      message: "Invalid State: State parameter mismatch",
+    });
+  }
+
+  states.delete(state);
+
+  res.render("callback", {
+    code: code,
+    state: state,
+    authServer: authServer,
+    clientId: clientId,
+    clientSecret: clientSecret,
+    redirectUri: redirectUri,
+  });
+});
+
+app.get("/logout", (req, res) => {
+  res.redirect("/");
+});
+
+app.listen(3000);
+console.debug("[Client]: listens to http://localhost:3000");