OidcHttpMiddleware

OidcHttpMiddleware extends BaseMiddleware and guards Fastify HTTP routes. It verifies the Authorization: Bearer <token> header and injects the resolved user context onto the request object.

Registration

import { OidcHttpMiddleware } from "ioserver-oidc";

server.addController({
  name: "profile",
  controller: ProfileController,
  middlewares: [OidcHttpMiddleware],
});

The middleware applies to all routes of the controller. To leave some routes unprotected, split them across two controllers — one with the middleware, one without.

Request flow

1. Extracts the Bearer token from the Authorization header
2. Resolves OidcConfig from appHandle.oidcConfig.getConfig() (or falls back to process.env)
3. Calls verifyOidcToken(token, config) — verifies signature, iss, aud, and expiry via remote JWKS
4. If appHandle.users.findOrCreate(sub, { email, name }) is available, provisions the local user record on first access
5. Rejects accounts where isDisabled === true with 403
6. Injects auth context onto the request object and calls the route handler

Injected context

After successful authentication the following properties are available on the Fastify request object:

In TypeScript, cast the request to any or augment the Fastify type declarations in your app to access these properties without type errors:

import type { FastifyRequest, FastifyReply } from "fastify";

class ProfileController extends BaseController {
  async getMe(request: FastifyRequest, reply: FastifyReply) {
    const req = request as any;
    reply.send({
      userId: req.userId,
      role: req.userRole,
      permissions: req.permissions,
    });
  }
}

Error responses

Response body format:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "ERR_AUTH_TOKEN_REQUIRED",
  "message": "Bearer token required."
}

Config caching

The OidcConfig is resolved on the first request and cached on the middleware instance for the lifetime of the server process. Restarting the server clears the cache and re-reads environment variables.

Source

src/OidcHttpMiddleware.ts