Installation

Prerequisites

ioserver must be installed in your project first — ioserver-oidc declares it as a peer dependency. See the IOServer installation guide if you have not set up an IOServer project yet.

Install the package

# pnpm (recommended)
pnpm add ioserver-oidc

# npm
npm install ioserver-oidc

# yarn
yarn add ioserver-oidc

jose is bundled as a direct dependency — no extra installation is required.

TypeScript configuration

ioserver-oidc is an ESM-only package. Your tsconfig.json must target ES2020 or later and use "module": "NodeNext" or "module": "ESNext":

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true
  }
}

If your IOServer project uses "module": "commonjs" (default in many templates), you have two options:

1. Migrate to ESM — Change "type": "module" in package.json and update tsconfig.json. See the Node.js ESM guide.
2. Use dynamic import — Import ioserver-oidc via a dynamic import() call at startup, which works in CommonJS projects.

Environment variables

OidcConfigManager reads the following variables at startup. Set them in your .env file or deployment environment:

# Required
AUTH_SERVICE_URL=https://auth.example.com
AUTH_SERVICE_APP_SLUG=my-app

# Optional — override auto-discovered endpoints
AUTH_SERVICE_JWKS_URI=https://auth.example.com/api/auth/jwks
AUTH_SERVICE_ISSUER=https://auth.example.com

Variables are read once at server startup by OidcConfigManager.start(). If OidcConfigManager is not registered, the middlewares read them lazily on the first request without caching between restarts — registering the manager is strongly recommended.