{"id":17861,"library":"okta-oidc-middleware","title":"Okta Node.js OIDC Middleware","description":"The `@okta/oidc-middleware` package provides an OpenID Connect middleware for Express.js applications, simplifying the integration of Okta's authorization code flow. It handles redirecting users to Okta for authentication, processing the callback, and establishing a local session to store user context. The library currently maintains a stable major version series of 2.x, with the latest release being 4.2.0, following semantic versioning and Okta's library version policy. A key differentiator is its seamless integration with Express, managing OIDC complexities like token exchange and session maintenance, while relying on `express-session` for local session storage. It's designed to quickly enable secure authentication for Node.js web applications, abstracting away much of the underlying OIDC protocol details.","status":"active","version":"0.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/okta/okta-oidc-js","tags":["javascript","okta","oidc","OpenId Connect","authentication","auth"],"install":[{"cmd":"npm install okta-oidc-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add okta-oidc-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add okta-oidc-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for local session management to store user context after OIDC flow. Must be configured before `@okta/oidc-middleware`.","package":"express-session","optional":false}],"imports":[{"note":"CommonJS import style, commonly used in Node.js applications as shown in quickstart examples. The library provides both CJS and ESM exports.","wrong":"const ExpressOIDC = require('@okta/oidc-middleware').ExpressOIDC;","symbol":"ExpressOIDC","correct":"const { ExpressOIDC } = require('@okta/oidc-middleware');"},{"note":"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.","wrong":"import ExpressOIDC from '@okta/oidc-middleware';","symbol":"ExpressOIDC","correct":"import { ExpressOIDC } from '@okta/oidc-middleware';"},{"note":"TypeScript type import for configuring the `ExpressOIDC` instance. Available since `jwt-verifier` v2.1.0, which ships types and is a dependency.","symbol":"OktaOIDCAuthOptions","correct":"import type { OktaOIDCAuthOptions } from '@okta/oidc-middleware';"}],"quickstart":{"code":"const express = require('express');\nconst session = require('express-session');\nconst { ExpressOIDC } = require('@okta/oidc-middleware');\n\nconst app = express();\n\nconst oidc = new ExpressOIDC({\n  issuer: process.env.OKTA_ISSUER || 'https://{yourOktaDomain}/oauth2/default',\n  client_id: process.env.OKTA_CLIENT_ID || '{clientId}',\n  client_secret: process.env.OKTA_CLIENT_SECRET || '{clientSecret}',\n  appBaseUrl: process.env.OKTA_APP_BASE_URL || 'http://localhost:8080',\n  scope: 'openid profile'\n});\n\napp.use(session({\n  secret: process.env.SESSION_SECRET || 'a-very-long-random-string-that-you-should-change',\n  resave: false,\n  saveUninitialized: false\n  // For production, replace MemoryStore with a persistent store (e.g., connect-redis)\n}));\napp.use(oidc.router);\n\napp.get('/', (req, res) => {\n  if (req.userContext) {\n    res.send(`\n      Hello ${req.userContext.userinfo.name}!\n      <form method=\"POST\" action=\"/logout\">\n        <button type=\"submit\">Logout</button>\n      </form>\n    `);\n  } else {\n    res.send('Please <a href=\"/login\">login</a>');\n  }\n});\n\napp.get('/protected', oidc.ensureAuthenticated(), (req, res) => {\n  res.send('This is a protected page. Welcome, ' + req.userContext.userinfo.name);\n});\n\nconst port = process.env.PORT || 8080;\noidc.on('ready', () => {\n  app.listen(port, () => console.log(`App has started on port ${port}`));\n});\noidc.on('error', err => {\n  console.error('OIDC error: ', err);\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Ensure 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`.","message":"The `@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.","severity":"breaking","affected_versions":">=@okta/jwt-verifier@2.0.0 (indirectly affects @okta/oidc-middleware versions using this dependency, e.g., >=4.x)"},{"fix":"Upgrade 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.","message":"Versions 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.","severity":"deprecated","affected_versions":"<2.0.0"},{"fix":"For production deployments, configure `express-session` with a persistent and robust session store like `connect-redis`, `connect-mongo`, or another compatible solution.","message":"The 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.","severity":"gotcha","affected_versions":"*"},{"fix":"Always 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.","message":"Older 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.","severity":"gotcha","affected_versions":"jwks-rsa <1.x (indirectly affecting older @okta/jwt-verifier and @okta/oidc-middleware versions)"},{"fix":"Consult 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.","message":"The `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.","severity":"breaking","affected_versions":">=@okta/okta-react@3.0.4"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Provide a strong, long, and securely generated secret string for `express-session`. Use environment variables to manage it: `secret: process.env.SESSION_SECRET`.","cause":"The `express-session` middleware requires a `secret` option, which was either omitted or empty.","error":"Error: secret must be set for session middleware"},{"fix":"Ensure `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.","cause":"The `req.userContext` object is not available, meaning the OIDC authentication flow has not completed or `oidc.router` was not properly configured/applied.","error":"TypeError: Cannot read properties of undefined (reading 'userContext')"},{"fix":"Verify 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.","cause":"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.","error":"No KID specified"},{"fix":"Ensure `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.","cause":"The OIDC endpoints (e.g., `/login`, `/authorization-code/callback`, `/logout`) are not correctly routed by the `oidc.router` middleware.","error":"Error: Not found: /login (or any configured OIDC endpoint)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}