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
    └── oidc-js-kasper     core + fetch + Kasper integration

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

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

Security Philosophy

The real security boundary in an OIDC application is the resource server, not the browser. oidc-js is designed around this principle.

Tokens are treated as opaque on the client. An access token is a bearer token — if an attacker steals it via XSS, they use it as-is. Client-side signature verification doesn't prevent that. The server must validate every token before granting access regardless of what the client does, making browser-side verification redundant rather than "defense in depth."

Tokens arrive over a trusted channel. In the Authorization Code + PKCE flow, the client exchanges the code for tokens directly with the IdP over TLS. The OpenID Connect spec explicitly permits this: "If the ID Token is received via direct communication between the Client and the Token Endpoint, the TLS server validation MAY be used to validate the issuer in place of checking the token signature" (OIDC Core 1.0 §3.1.3.7, step 6). If you can't trust the HTTPS channel, signature verification won't save you — an attacker who compromised your discovery or DNS could serve a validly signed token from a malicious IdP.

Where oidc-js invests instead:

• Memory-only token storage — tokens never touch localStorage or sessionStorage, limiting XSS-based token theft, the primary threat to SPAs
• Zero runtime dependencies — no dependency tree means no supply chain attack surface in the core package
• Modern refresh flow — uses refresh tokens instead of iframe-based silent auth, avoiding third-party cookie issues and the insecure workarounds developers resort to when iframes break

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 verified

• JWT signatures — tokens are decoded but not cryptographically verified. Per OIDC Core 1.0 §3.1.3.7, TLS validation may be used in place of signature verification when tokens are received directly from the token endpoint. If your application requires signature verification (e.g., server-side validation, zero-trust environments), validate tokens independently using the provider's JWKs.
• Access token contents — access tokens are treated as opaque strings. Server-side validation (introspection or signature verification) is the responsibility of your resource server.
• at_hash / c_hash claims — access token and code hash claims in the ID token are not validated.

Threat Model

Testing

The project has two layers of testing: unit tests for the functional core and each adapter, and E2E tests that run every adapter against a real OIDC identity provider.

Unit tests

The functional core and every framework adapter have unit tests that validate protocol logic, state management, and component behavior with plain input/output — no mocked fetch or window.

pnpm -r test    # Run all unit tests

E2E tests

26 end-to-end tests run real OIDC flows against a live Autentico instance — no mocked endpoints, no simulated responses. Every test runs on all 8 framework adapters.

Every test also asserts the exact sequence of OIDC network requests (discovery → token → userinfo) to catch 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. A separate stress workflow runs the full suite repeatedly to surface race conditions and flaky tests.

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

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

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 Decisions

These are deliberate constraints, not missing features:

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)
• expiryBuffer 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 unit tests
pnpm test

# Run E2E tests (sequential, all 8 frameworks)
pnpm test:e2e

# Run E2E tests in parallel (4 at a time)
MAX_PARALLEL=4 pnpm test:e2e

# Run E2E stress test (10x repetition per framework)
pnpm test:stress

# 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