Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ExpressOIDC
✓ const { ExpressOIDC } = require('@okta/oidc-middleware');
✗ const ExpressOIDC = require('@okta/oidc-middleware').ExpressOIDC;
CommonJS import style, commonly used in Node.js applications as shown in quickstart examples. The library provides both CJS and ESM exports.
ExpressOIDC
✓ import { ExpressOIDC } from '@okta/oidc-middleware';
✗ import ExpressOIDC from '@okta/oidc-middleware';
ESM (ECMAScript Module) import style. The library is dual-packaged, supporting both CJS and ESM for modern Node.js environments. `ExpressOIDC` is a named export.
OktaOIDCAuthOptions
✓ import type { OktaOIDCAuthOptions } from '@okta/oidc-middleware';
TypeScript type import for configuring the `ExpressOIDC` instance. Available since `jwt-verifier` v2.1.0, which ships types and is a dependency.
This example initializes an Express application with `express-session` and `@okta/oidc-middleware`, configuring a basic OIDC flow for user login and a protected route.
const express = require('express');
const session = require('express-session');
const { ExpressOIDC } = require('@okta/oidc-middleware');
const app = express();
const oidc = new ExpressOIDC({
issuer: process.env.OKTA_ISSUER || 'https://{yourOktaDomain}/oauth2/default',
client_id: process.env.OKTA_CLIENT_ID || '{clientId}',
client_secret: process.env.OKTA_CLIENT_SECRET || '{clientSecret}',
appBaseUrl: process.env.OKTA_APP_BASE_URL || 'http://localhost:8080',
scope: 'openid profile'
});
app.use(session({
secret: process.env.SESSION_SECRET || 'a-very-long-random-string-that-you-should-change',
resave: false,
saveUninitialized: false
// For production, replace MemoryStore with a persistent store (e.g., connect-redis)
}));
app.use(oidc.router);
app.get('/', (req, res) => {
if (req.userContext) {
res.send(`
Hello ${req.userContext.userinfo.name}!
<form method="POST" action="/logout">
<button type="submit">Logout</button>
</form>
`);
} else {
res.send('Please <a href="/login">login</a>');
}
});
app.get('/protected', oidc.ensureAuthenticated(), (req, res) => {
res.send('This is a protected page. Welcome, ' + req.userContext.userinfo.name);
});
const port = process.env.PORT || 8080;
oidc.on('ready', () => {
app.listen(port, () => console.log(`App has started on port ${port}`));
});
oidc.on('error', err => {
console.error('OIDC error: ', err);
});
Debug
Known issues
breakingThe `@okta/jwt-verifier` dependency (v2.0.0 and higher) will now throw an error "No KID specified" if a JWT token lacks a 'kid' (Key ID) header. This is a breaking change for applications that receive tokens without 'kid' headers.fixEnsure your Okta authorization server is configured to issue JWTs with a 'kid' header in the token. If using custom tokens, ensure they conform to this expectation. Upgrade to the latest stable versions of both `@okta/oidc-middleware` and `@okta/jwt-verifier`.
affects: >=@okta/jwt-verifier@2.0.0 (indirectly affects @okta/oidc-middleware versions using this dependency, e.g., >=4.x)
deprecatedVersions 0.x and 1.x of `@okta/oidc-middleware` are considered deprecated or retired and should not be used in new projects or production environments due to potential security vulnerabilities and lack of maintenance.fixUpgrade to the current stable major version series, which is 2.x or higher (latest is 4.x), to ensure you receive security updates and bug fixes.
affects: <2.0.0
gotchaThe default `MemoryStore` provided by `express-session` is explicitly not designed for production use. Using it in production can lead to session loss on server restarts, scaling issues, and potential security vulnerabilities.fixFor production deployments, configure `express-session` with a persistent and robust session store like `connect-redis`, `connect-mongo`, or another compatible solution.
affects: *
gotchaOlder versions of `@okta/jwt-verifier` and its sub-dependencies, such as `jwks-rsa`, have contained security vulnerabilities that were addressed in later patches. Running outdated versions can expose your application to known exploits.fixAlways use the latest stable version of `@okta/oidc-middleware` to ensure all underlying dependencies are up-to-date with security patches. Regularly review dependency updates.
affects: jwks-rsa <1.x (indirectly affecting older @okta/jwt-verifier and @okta/oidc-middleware versions)
breakingThe `onSessionExpired` behavior in `@okta/okta-react` (part of the same monorepo) was removed in version 3.0.4. While not directly `oidc-middleware`, it indicates a pattern of changes in how session expiration is handled across Okta libraries. Developers should review their session management strategy.fixConsult the specific library's README for current guidance on handling session expiration. For `@okta/oidc-middleware`, custom logic might be required around session invalidation or token refresh.
affects: >=@okta/okta-react@3.0.4
Errors
Common errors & fixes
Error: secret must be set for session middleware
The `express-session` middleware requires a `secret` option, which was either omitted or empty.
fixProvide a strong, long, and securely generated secret string for `express-session`. Use environment variables to manage it: `secret: process.env.SESSION_SECRET`.
TypeError: Cannot read properties of undefined (reading 'userContext')
The `req.userContext` object is not available, meaning the OIDC authentication flow has not completed or `oidc.router` was not properly configured/applied.
fixEnsure `app.use(oidc.router)` is called, and that `express-session` middleware is registered *before* `oidc.router`. Verify that the user has successfully logged in via Okta and completed the OIDC redirect flow.
No KID specified
The JWT (ID Token or Access Token) received from Okta or another source does not contain a 'kid' (Key ID) header, and `@okta/jwt-verifier` is configured to expect one.
fixVerify that your Okta Authorization Server is configured to include 'kid' headers in issued tokens. If you're using custom tokens, ensure they adhere to this standard. This typically requires no change for standard Okta configurations.
Error: Not found: /login (or any configured OIDC endpoint)
The OIDC endpoints (e.g., `/login`, `/authorization-code/callback`, `/logout`) are not correctly routed by the `oidc.router` middleware.
fixEnsure `app.use(oidc.router)` is called in your Express application. Check your `appBaseUrl` configuration to ensure it matches your application's base URL and redirect URIs in Okta.
Audit
Dependencies
express-sessionrequiredRequired for local session management to store user context after OIDC flow. Must be configured before `@okta/oidc-middleware`.