{"id":15741,"library":"oidc-client","title":"OpenID Connect & OAuth2 Client","description":"oidc-client is a comprehensive JavaScript client library for OpenID Connect (OIDC) and OAuth2, designed to facilitate secure authentication and authorization in web applications. It handles complex OAuth2 flows, including Authorization Code Flow with PKCE, implicit flow, and refresh token management, abstracting away much of the underlying protocol complexity. Developed by IdentityModel, it maintains a strong focus on security and adherence to OIDC/OAuth2 specifications. The current stable version is 1.11.5, with an active development cycle characterized by frequent bug fix releases and minor feature updates approximately every 1-2 months, as evidenced by recent patch versions. Key differentiators include its robust handling of session management, silent token renewal, and extensive configurability, making it suitable for a wide range of single-page applications and client-side integrations.","status":"active","version":"1.11.5","language":"javascript","source_language":"en","source_url":"https://github.com/IdentityModel/oidc-client-js","tags":["javascript","typescript"],"install":[{"cmd":"npm install oidc-client","lang":"bash","label":"npm"},{"cmd":"yarn add oidc-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add oidc-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"UserManager is the primary class for managing user authentication and tokens.","wrong":"const UserManager = require('oidc-client').UserManager","symbol":"UserManager","correct":"import { UserManager } from 'oidc-client'"},{"note":"Used to configure custom storage for OIDC state, typically LocalStorage or SessionStorage.","wrong":"const WebStorageStateStore = require('oidc-client').WebStorageStateStore","symbol":"WebStorageStateStore","correct":"import { WebStorageStateStore } from 'oidc-client'"},{"note":"Provides a simple logging mechanism for debugging purposes. Configure its level for verbose output.","wrong":"const Log = require('oidc-client').Log","symbol":"Log","correct":"import { Log } from 'oidc-client'"},{"note":"The core OIDC client, providing low-level protocol operations for scenarios not requiring full UserManager capabilities.","wrong":"const OidcClient = require('oidc-client').OidcClient","symbol":"OidcClient","correct":"import { OidcClient } from 'oidc-client'"}],"quickstart":{"code":"import { UserManager, WebStorageStateStore, Log } from 'oidc-client';\n\nLog.logger = console;\nLog.level = Log.INFO;\n\nconst settings = {\n  authority: 'https://demo.duendesoftware.com/', // Your OIDC provider authority\n  client_id: 'interactive.public', // Your client ID\n  redirect_uri: 'http://localhost:3000/callback', // Your app's redirect URI\n  response_type: 'code',\n  scope: 'openid profile api offline_access',\n  post_logout_redirect_uri: 'http://localhost:3000/', // Where to go after logout\n  userStore: new WebStorageStateStore({ store: window.localStorage }),\n  automaticSilentRenew: true,\n  // Optional: configure popup for signin/signout if needed\n  // popup_redirect_uri: 'http://localhost:3000/popup.html',\n  // popup_post_logout_redirect_uri: 'http://localhost:3000/popup.html',\n};\n\nconst userManager = new UserManager(settings);\n\nasync function signIn() {\n  try {\n    await userManager.signinRedirect();\n  } catch (error) {\n    Log.error(\"Signin error\", error);\n  }\n}\n\nasync function signOut() {\n  try {\n    await userManager.signoutRedirect();\n  } catch (error) {\n    Log.error(\"Signout error\", error);\n  }\n}\n\nasync function getUser() {\n  try {\n    const user = await userManager.getUser();\n    if (user) {\n      Log.info(\"User loaded:\", user);\n      console.log('Access Token:', user.access_token);\n      console.log('ID Token:', user.id_token);\n    } else {\n      Log.info(\"No user logged in.\");\n    }\n    return user;\n  } catch (error) {\n    Log.error(\"Error getting user:\", error);\n    return null;\n  }\n}\n\n// Example usage (e.g., in a SPA entry point)\nasync function initializeApp() {\n  const path = window.location.pathname;\n  if (path === '/callback') {\n    try {\n      const user = await userManager.signinRedirectCallback();\n      Log.info(\"Signin redirect callback processed. User:\", user);\n      window.history.replaceState({}, document.title, '/'); // Clean up URL\n    } catch (error) {\n      Log.error(\"Error in signin redirect callback\", error);\n    }\n  } else {\n    const user = await getUser();\n    if (!user) {\n      console.log('No user, initiating sign-in...');\n      signIn();\n    } else {\n      console.log('User already logged in.');\n      // For demonstration purposes, you might want to call sign out later\n      // setTimeout(signOut, 60000);\n    }\n  }\n}\n\ninitializeApp();\n","lang":"typescript","description":"Demonstrates the basic setup of UserManager for OIDC authentication, including configuration for sign-in, sign-out, and handling redirect callbacks for a Single Page Application (SPA)."},"warnings":[{"fix":"Ensure you are on version 1.11.5 or newer. Carefully review your `OidcClientSettings` and the discovered OIDC metadata if encountering issues with endpoint or configuration resolution.","message":"Metadata merging issues can lead to incorrect configuration. Specifically, `metadataSeed` was improperly merged and returned in versions prior to 1.11.5, potentially causing runtime errors or unexpected behavior during discovery.","severity":"gotcha","affected_versions":"<1.11.5"},{"fix":"Upgrade to version 1.11.3 or later if you intend to use PKCE within a popup workflow. Alternatively, use redirect-based flows.","message":"Authentication Code Flow with PKCE (Proof Key for Code Exchange) was not supported for popup windows in versions prior to 1.11.3, limiting flexibility for certain authentication UX patterns.","severity":"gotcha","affected_versions":"<1.11.3"},{"fix":"Remove any references to `getEpochTime` from your `OidcClientSettings`. The library now internally manages time-related calculations, or uses standard JavaScript Date objects.","message":"The `getEpochTime` method was removed from `OidcClientSettings` in version 1.11.1. If you were customizing epoch time calculation through this setting, your application will break.","severity":"breaking","affected_versions":">=1.11.1"},{"fix":"Always provide a `UserManagerSettings` object to the `UserManager` constructor. Even if empty, pass `{}`. E.g., `new UserManager({})`.","message":"TypeScript typings for `UserManager` in versions prior to 1.10.1 no longer allowed instantiation without options. This broke existing TypeScript code that initialized `UserManager` without an explicit settings object.","severity":"breaking","affected_versions":">=1.10.1"},{"fix":"While `oidc-client` aims for promise compatibility, if encountering issues, consider using native Promises or an alternative promise library, or upgrade to the latest version where this might be resolved or mitigated.","message":"The `SessionMonitor` component could cause warnings when used in conjunction with the Bluebird promise library. This was a specific interaction issue reported in version 1.11.1.","severity":"gotcha","affected_versions":">=1.11.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade to `oidc-client@1.11.2` or newer to get the corrected typings for the `getToken` method.","cause":"Incorrect or missing TypeScript definitions for optional parameters in the `getToken` method prior to version 1.11.2.","error":"TS typings error in getToken for optional param"},{"fix":"Instantiate `UserManager` with an empty object if no settings are needed: `new UserManager({});`","cause":"The TypeScript definitions were updated in version 1.10.1 to require a `UserManagerSettings` object when instantiating `UserManager`, even if empty.","error":"New TypeScript typings don't allow optionless UserManager"},{"fix":"Ensure your OIDC provider is returning a correctly formatted sign-out response. Upgrade to `oidc-client@1.9.1` or newer which includes a fix for this specific validation issue.","cause":"This error, reported in versions prior to 1.9.1, indicates that the sign-out response validation logic failed to find an expected 'id' property, likely due to an invalid or malformed sign-out response from the OIDC provider.","error":"TypeError: Cannot read property 'id' of undefined in validateSignoutResponse"},{"fix":"Upgrade `oidc-client` to version 1.10.0 or newer. This version included specific fixes to address Angular 8 build errors, likely related to TypeScript configurations or module bundling.","cause":"Specific build incompatibilities or incorrect module resolution issues were reported with Angular 8 in versions prior to 1.10.0.","error":"Angular 8 build error: Cannot read property 'id' of undefined or similar build failures related to `oidc-client`."}],"ecosystem":"npm"}