oidc-js

Drop-in OIDC authentication for every JavaScript framework.

Why oidc-js

Most OIDC libraries couple protocol logic with a specific HTTP and framework model. This can make it harder to integrate cleanly with frameworks that have their own patterns (e.g., Angular's HttpClient), forces tests to mock window and network calls, and leads every framework to re-implement the same token exchange.

oidc-js separates these concerns:

• Functional core — pure functions that build requests and parse responses. No fetch, no storage, no side effects. Deterministic and testable with plain input/output.
• Thin adapters — each framework composes the core with its own HTTP layer and reactivity. Angular uses HttpClient. React uses hooks. Svelte uses runes. No framework-specific workarounds.
• Zero dependencies — the core uses only the Web Crypto API. Works in any JS runtime: browser, Node, Deno, Bun, Workers.

When Not to Use oidc-js

• Server-side applications that require JWT signature verification — the core decodes but does not cryptographically verify tokens. Use a server-side library with JWK validation instead.
• Applications that require persistent sessions across page reloads without refresh tokens — tokens are stored in memory only and are lost on navigation or refresh.
• Environments with strict compliance requirements (e.g., FIPS, FedRAMP) — this library does not implement the additional validation layers those standards require.

Packages

Architecture

oidc-js-core              Pure functions. No IO. No state.
    |
    ├── oidc-js            core + fetch + sessionStorage
    ├── oidc-js-react      core + fetch + React context/hooks
    ├── oidc-js-vue        core + fetch + Vue plugin/composables
    ├── oidc-js-svelte     core + fetch + Svelte 5 runes/context
    ├── oidc-js-angular    core + HttpClient + Angular signals/DI
    ├── oidc-js-solid      core + fetch + Solid signals/context
    ├── oidc-js-preact     core + fetch + Preact hooks
    └── oidc-js-lit        core + fetch + Lit reactive controllers

The core never calls fetch or touches browser APIs (except Web Crypto for PKCE). Each framework adapter composes the core functions with its own HTTP layer and state management:

• Angular uses HttpClient with its interceptor chain, not a fetch workaround
• React/Vue/Svelte/Solid/Preact/Lit use fetch directly, lightweight with no wrapper overhead
• Node.js/Deno/Bun work out of the box via oidc-js-core, no browser polyfills required
• Tests are trivial: pure input/output, no mocking fetch or window

Quick Start

Install the adapter for your framework:

npm install oidc-js-react    # or oidc-js-vue, oidc-js-svelte, etc.

Wrap your app with the provider:

import { AuthProvider } from "oidc-js-react";

function App() {
  return (
    <AuthProvider
      issuer="https://auth.example.com"
      clientId="my-app"
      redirectUri="http://localhost:3000/callback"
      scopes={["openid", "profile", "email"]}
    >
      <MyApp />
    </AuthProvider>
  );
}

Use the hook anywhere:

import { useAuth } from "oidc-js-react";

function Profile() {
  const { isAuthenticated, user, actions } = useAuth();

  if (!isAuthenticated) {
    return <button onClick={() => actions.login()}>Log in</button>;
  }

  return <p>Hello, {user?.claims?.name}</p>;
}

See each package's README for framework-specific setup, full API reference, and configuration options.

Security Model

What is validated

• State parameter — generated per login, validated on callback. Prevents CSRF attacks on the authorization flow.
• Nonce — bound to the ID token. If the ID token's nonce claim doesn't match the value sent during authorization, token parsing throws NONCE_MISMATCH. Prevents token replay.
• PKCE (S256) — every authorization request uses a code verifier + SHA-256 challenge. Prevents authorization code interception.
• Discovery issuer — parseDiscoveryResponse validates that the issuer field in the discovery document matches the expected issuer exactly. Prevents mix-up attacks.
• Token response structure — parseTokenResponse validates required fields and computes expires_at from the response. Malformed or error responses throw typed errors.

What is NOT validated

• JWT signatures — decodeJwtPayload and parseIdTokenClaims decode the JWT payload without verifying the signature. In browser-based applications, tokens are obtained directly from the token endpoint over TLS, and the client relies on the HTTPS channel and the authorization server for integrity. However, this library does not perform cryptographic signature verification. If your application requires token verification (e.g., server-side validation, zero-trust environments), you must validate tokens independently using the provider's JWKs.
• Access token contents — access tokens are treated as opaque strings. The library does not parse or validate their structure. Server-side validation (introspection or signature verification) is the responsibility of your resource server.
• at_hash / c_hash claims — the library does not validate access token or code hash claims in the ID token.

Threat Model

Testing

Every framework adapter runs against a real OIDC identity provider — no mocked endpoints, no simulated responses. The E2E suite spins up a live Autentico instance, performs actual OAuth 2.0 flows through a browser, and asserts on both the UI state and the exact OIDC network traffic.

Why a dedicated test IdP

We use Autentico, a lightweight Go-based IdP built by the same team:

• Fast startup (~500ms) — enables per-run isolation with no shared state between test runs
• Admin API — test users, clients, and token lifetimes are configured programmatically, not through a UI
• Deterministic — no rate limits, no external dependencies, no flaky third-party auth servers
• Repeated execution — the suite runs 10x per CI execution to detect race conditions and timing-dependent failures

This testing strategy prioritizes determinism and reproducibility over provider diversity in CI. Provider compatibility is validated separately (see below).

Test coverage

16 tests cover the full OIDC lifecycle across all 8 framework adapters:

Every test also asserts the exact sequence of OIDC fetch requests (discovery → token → userinfo) and page navigations (/oauth2/authorize, /oauth2/logout) to verify no unexpected network calls are made. This catches regressions that UI-only assertions would miss — like a silent double-refresh or a missing discovery call.

The test harness is framework-agnostic: each adapter implements the same data-testid contract and runs the same Playwright spec. See tests/e2e/harness.md for the full contract.

Provider Compatibility

The library follows the OIDC and OAuth 2.0 specifications closely (see RFC Compliance). However, real-world providers may have non-standard behaviors or quirks. Testing against your specific provider before deploying to production is strongly recommended. If you've tested with a provider not listed here, contributions are welcome.

Design Tradeoffs

These are deliberate constraints, not missing features:

Architectural Guarantees

• Core is side-effect free — no IO, no global state, no implicit network calls
• All protocol operations are explicit — no hidden fetches, no background iframes, no silent token acquisition
• Framework adapters are thin and replaceable — swapping frameworks means changing the adapter, not the auth logic
• No tokens are persisted beyond memory — the most secure default for browser-based applications

Error Handling

All errors throw OidcError with a typed code property:

import { OidcError } from "oidc-js-core";

try {
  const result = parseCallbackUrl(url, expectedState);
} catch (e) {
  if (e instanceof OidcError) {
    switch (e.code) {
      case "STATE_MISMATCH":
        // CSRF protection triggered
        break;
      case "AUTHORIZATION_ERROR":
        // Server returned an error
        break;
    }
  }
}

RFC Compliance

Every validation and return path in the source code is annotated with the specific RFC section it implements. The library conforms to:

• RFC 6749 — OAuth 2.0 Authorization Framework
• RFC 7636 — Proof Key for Code Exchange (PKCE)
• RFC 7009 — OAuth 2.0 Token Revocation
• RFC 7662 — OAuth 2.0 Token Introspection
• OpenID Connect Core 1.0
• OpenID Connect Discovery 1.0
• OpenID Connect RP-Initiated Logout 1.0

Production Readiness Checklist

Before deploying to production, verify:

• Tested against your specific OIDC provider (discovery, login, token exchange, refresh, logout)
• HTTPS enforced in all environments (tokens travel over TLS)
• Refresh token rotation enabled at your IdP (prevents stolen refresh token reuse)
• tokenExpirationBuffer configured appropriately (default: 30 seconds)
• CSP headers configured (mitigates XSS, the primary threat to SPA token storage)
• postLogoutRedirectUri set correctly for your IdP
• Error handling implemented for OidcError codes your app may encounter
• Verified that decodeJwtPayload is not used for server-side trust decisions

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Build core only
pnpm --filter oidc-js-core build

# Run tests
pnpm --filter oidc-js-core test

# Type check
pnpm --filter oidc-js-core lint

Tech Stack

• pnpm workspaces for monorepo management
• TypeScript in strict mode
• Vite 8 library mode builds (dual ESM/CJS)
• Vitest 4 test runner
• Playwright for E2E tests

License

MIT