β Logged in as ${req.session.user.username}
` : `β Not logged in
` } `); }); // Protected profile route - expressRequiresAuth() middleware app.get("/profile", expressRequiresAuth(), (req, res) => { res.send(`${JSON.stringify(req.session.user, null, 2)}
`);
});
app.listen(port, () => {
console.log(`
π BlitzWare Express Example running at http://localhost:${port}
π Routes:
β’ GET / - Home page
β’ GET /profile - Protected profile page
β’ GET /login - Login (automatic)
β’ GET /logout - Logout (automatic)
π Setup:
1. Set BLITZWARE_CLIENT_ID and BLITZWARE_CLIENT_SECRET in .env
2. Visit http://localhost:${port}/login to authenticate
`);
});
module.exports = app;
```
{% endcode %}
## 5) Koa setup
{% code lineNumbers="true" %}
```javascript
const path = require("path");
require("dotenv").config({ path: path.join(__dirname, "../.env") });
const Koa = require("koa");
const Router = require("@koa/router");
const KoaSession = require("koa-session");
const session =
KoaSession && KoaSession.default ? KoaSession.default : KoaSession;
const bodyParser = require("koa-bodyparser");
const { koaAuth, koaRequiresAuth } = require("blitzware-node-web-sdk");
const app = new Koa();
const router = new Router();
const port = process.env.PORT || 3001;
// BlitzWare configuration
const config = {
authRequired: false, // Don't require auth for all routes
clientId: process.env.BLITZWARE_CLIENT_ID || "your-client-id",
clientSecret: process.env.BLITZWARE_CLIENT_SECRET || "your-client-secret",
redirectUri:
process.env.BLITZWARE_REDIRECT_URI || `http://localhost:${port}/callback`,
secret: process.env.SESSION_SECRET || "LONG_RANDOM_STRING",
// baseUrl: process.env.BLITZWARE_BASE_URL, // Optional: custom auth server
};
// Koa requires signing keys for sessions
app.keys = [config.secret];
// Session middleware
app.use(session(app));
app.use(bodyParser());
// BlitzWare auth router attaches /login, /logout, and /callback routes
app.use(koaAuth(config));
// Home route - ctx.session.user is provided from the auth router
router.get("/", async (ctx) => {
ctx.type = "html";
ctx.body = `
β Logged in as ${ctx.session.user.username}
` : `β Not logged in
` } `; }); // Protected profile route - koaRequiresAuth() middleware router.get("/profile", koaRequiresAuth(), async (ctx) => { ctx.type = "html"; ctx.body = `${JSON.stringify(ctx.session.user, null, 2)}
`;
});
app.use(router.routes());
app.use(router.allowedMethods());
app.listen(port, () => {
console.log(`
π BlitzWare Koa Example running at http://localhost:${port}
π Routes:
β’ GET / - Home page
β’ GET /profile - Protected profile page
β’ GET /login - Login (automatic)
β’ GET /logout - Logout (automatic)
π Setup:
1. Set BLITZWARE_CLIENT_ID and BLITZWARE_CLIENT_SECRET in .env
2. Visit http://localhost:${port}/login to authenticate
`);
});
```
{% endcode %}
### 6) How it works
* PKCE + state: The SDK generates a `state` and PKCE verifier/challenge.
* `state` defends against CSRF
* PKCE protects the code exchange
#### Automatic Routes
When you use `expressAuth()` or `koaAuth()`, the following routes are created automatically:
* `GET /login` - Initiates OAuth login flow
* `GET /logout` - Logs out user and clears session
* `GET /callback` - OAuth callback handler
#### Protection
The SDK provides middleware to protect routes and enforce authorization:
**Authentication Middleware**
* `expressRequiresAuth()` / `koaRequiresAuth()` - Ensures a user is logged in before accessing a route. Redirects to `/login` if not authenticated.
**Express Example:**
```js
app.get("/profile", expressRequiresAuth(), (req, res) => {
res.json({ user: req.session.user });
});
```
**Koa Example:**
```js
router.get("/profile", koaRequiresAuth(), async (ctx) => {
ctx.body = { user: ctx.session.user };
});
```
**Role-Based Authorization Middleware**
* `expressRequiresRole(role)` / `koaRequiresRole(role)` - Ensures a user has a specific role. Returns 403 Forbidden if the user doesn't have the required role.
**Express Example:**
```js
const { expressRequiresAuth, expressRequiresRole } = require("blitzware-node-sdk");
// Admin-only route
app.get("/admin",
expressRequiresAuth(),
expressRequiresRole("admin"),
(req, res) => {
res.send("Admin Dashboard");
}
);
```
**Koa Example:**
```js
const { koaRequiresAuth, koaRequiresRole } = require("blitzware-node-sdk");
// Admin-only route
router.get("/admin",
koaRequiresAuth(),
koaRequiresRole("admin"),
async (ctx) => {
ctx.body = "Admin Dashboard";
}
);
```
**Note:** These middleware functions check for roles stored in `user.roles` array. They do not perform token introspection by default.
#### Logout (front-channel)
The SDK performs a front-channel logout: it serves a small HTML page that POSTs to the auth service (so auth-service cookies are sent) and then redirects back to your app.
***
If you need additional features β token introspection on each request, automatic refresh using `session.refreshToken`, or other behavior β open an issue or PR and I can add an opt-in option such as `requiresAuth({ validateToken: true })`.
***
License: MIT
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.blitzware.xyz/oauth/quickstart/webapp/node.md?ask=