OidcConfigManager

OidcConfigManager extends BaseManager and provides a centralised, cached OIDC configuration to all OIDC middlewares registered on the same server instance.

Registration

import { OidcConfigManager } from "ioserver-oidc";

server.addManager({ name: "oidcConfig", manager: OidcConfigManager });

The name must be "oidcConfig". The middlewares look up appHandle.oidcConfig by that exact key.

Behaviour

OidcConfigManager.start() is called automatically by IOServer during startup (before the HTTP/WebSocket listeners open). It reads environment variables once, validates the required ones, and stores the resolved OidcConfig internally.

After startup, any middleware calls appHandle.oidcConfig.getConfig() to retrieve the configuration. The result is a frozen object — mutations have no effect at runtime.

Methods

start(): Promise<void>

Called by the IOServer framework. Reads environment variables and populates the internal config. Throws if AUTH_SERVICE_URL or AUTH_SERVICE_APP_SLUG are missing.

getConfig(): OidcConfig

Returns the resolved OidcConfig. Throws Error if called before start() completes (i.e. before the server has fully started).

Fallback behaviour

If OidcConfigManager is not registered, OidcHttpMiddleware and OidcSocketMiddleware fall back to reading AUTH_SERVICE_URL and AUTH_SERVICE_APP_SLUG directly from process.env on the first request — without caching between server restarts.

Registering the manager is strongly recommended in production because:

• Configuration is validated at startup time (fail fast rather than fail on first request)
• The config object is cached once, avoiding repeated process.env lookups
• The startup log entry confirms which authServiceUrl and appSlug are in use

Environment variables

Startup log

When the manager starts successfully it emits a log at level 6 (verbose):

[OidcConfigManager] Initialized — authServiceUrl=https://auth.example.com, appSlug=my-app

This is visible when IOServer's verbose option is set to "DEBUG" or "VERBOSE".

Source

src/OidcConfigManager.ts