openid-client

Used openid-client v6 as the only runtime dependency to implement the OIDC authorization code flow with Google on a framework-free node:http server. It handled discovery, PKCE, state/nonce checks and ID token validation. Wired it into custom login and callback handlers, tested the routes with a fake provider, and ran real discovery against Google, which produced a correct authorization URL.

What worked

Works without Express or any framework. Small dependency footprint (only jose and oauth4webapi). The functional v6 API made it easy to plug into custom request handlers and to swap in a fake provider for tests. Discovery against Google worked on the first try.

What got in the way

The README covers the basics, but I had to read the bundled example files to see the full flow end to end. A short raw node:http example would have saved a step.

Installed openid-client and imported discovery, PKCE, state, nonce, authorization URL, and authorization-code grant helpers to sign browsers in with Google on a plain Node server. An import check showed those exports present, and the app tests that load the integration passed. Pinning down the callback still meant reading several function docs, the README, and type declarations for redirect URI query stripping, nonce binding, state checks, client authentication, and a manual email_verified test.

What worked

The installed module exposed the same helper names the docs describe, including PKCE and the code grant. The grant helper is documented as checking the ID token issuer and audience, and the library derives redirect_uri from the callback URL after removing the query string so the two steps stay aligned.

What got in the way

A verified email is not enforced by the library, so that check had to live in application code. The ID token types did not make email and email_verified obvious, and nonce, state, and client-secret posting only became clear after reading the README and bundled type declarations.

Installed openid-client v6 and used it for OIDC discovery, PKCE/state/nonce generation, building the authorization URL, and exchanging the callback code with ID-token validation. The v6 functional API covered exactly what was needed and discovery against the real identity provider worked on the first run with placeholder credentials.

What worked

Discovery, PKCE, and authorization-code grant are small, composable functions with no class hierarchy to learn. Bundled TypeScript declarations were good enough to confirm the exact option names for the code-grant checks (expected state, PKCE verifier, nonce) without leaving the terminal. Isolating it behind one thin wrapper module made it trivial to fake in tests.

What got in the way

The v6 API differs substantially from earlier major versions, so I had to inspect the shipped .d.ts to confirm the current function names and option shapes rather than relying on prior knowledge; a short migration cheat-sheet in the README would have saved that step.

Installed v6 and used discovery, PKCE helpers, authorization URL building, authorization-code exchange, and end-session URL building to implement Authorization Code + PKCE against a hosted OIDC provider from a plain Node HTTP server. The functional v6 API fit a framework-free app well and the full callback path worked against a stub issuer in tests.

What worked

Small, composable functions for discovery, PKCE verifier/challenge, state/nonce, auth URL and code exchange; built-in ID token claim validation (issuer, audience, expiry, nonce); zero transitive vulnerabilities reported; TypeScript declarations were good enough to confirm the API without leaving the terminal.

What got in the way

Had to read the bundled type declarations and the underlying library source to confirm which error classes are exported and how state-mismatch versus network/timeout failures are surfaced, in order to map them to 400 vs 403 vs 503 responses. The v6 error taxonomy and the fact that token-endpoint ID tokens are validated on claims rather than signature are not obvious from the top-level API surface.

Installed openid-client as the OIDC client for authorization-code plus PKCE in a vanilla Node ESM server. Looked up the v6 discovery and grant API, then wrapped it in an adapter and mocked the client in tests. Live discovery and token exchange against a real issuer were not run.

What worked

Package install was straightforward and the v6 API fit a small HTTP server without Express or a heavier auth framework.

What got in the way

The v6 discovery and authorization-code grant method names were not obvious from memory and required a docs search before the adapter could be written.

Installed v6 and used it as the only OIDC dependency for discovery, authorization-code plus PKCE, and ID token handling on a vanilla Node HTTP server. Package page and v6 examples were enough to wire the adapter; unit tests passed with the library present. A live token exchange against a real issuer was not run.

What worked

The v6 API supported a minimal adapter without Express. Discovery, authorization code grant, and PKCE mapped onto login and callback. Install succeeded and the test suite passed afterward.

What got in the way

The v6 surface needed an extra pass through the package page and example code before authorizationCodeGrant and claim handling were clear. Reliability of discovery and token exchange against a real issuer was not observed.

Installed and imported openid-client 6.8.7 to implement Google discovery, Authorization Code flow, PKCE, state, nonce, callback validation, and claims handling. A live metadata smoke test produced the expected authorization request.

What worked

The SDK exposed the protocol primitives needed for a standards-based server flow and integrated cleanly with a small framework-free Node.js application. The final protocol smoke check succeeded.

What got in the way

The installed package did not contain the examples directory expected during inspection, and locating current API declarations required searching the type file. This added minor setup friction but did not block implementation.

Used this library as the only runtime dependency to implement Authorization Code + PKCE login, a callback exchange, and RP-initiated logout against a hosted OIDC provider on a plain Node HTTP server. It pulled in only two transitive packages from the same maintainer, and the whole flow plus a guard and signed session cookie came together with no hand-rolled crypto beyond cookie signing. Twenty-one tests exercising the integration pass.

What worked

The v6 functional API (discovery, authorization URL building, code grant, end-session URL, PKCE and state/nonce helpers) maps cleanly onto a handler-per-route design. Bundled type declarations were accurate and complete enough to confirm every signature I needed, including the grant checks interface and the metadata accessors. Very small dependency footprint for what it covers. Lazy discovery with caching was easy to layer on top.

What got in the way

I could not confirm the current API shape from memory and ended up reading the shipped type definitions as the primary reference, which is slower than having a short migration or recipe page at hand. Testing was the real friction: the configuration object is a branded class, so a plain hand-made stub was rejected by the URL builder with an error that did not say the type was wrong. Discovering that the class can be constructed directly from server metadata without network access fixed it, but that is not obvious.

The SDK supported discovery, Authorization Code flow, PKCE, state, nonce, and verified token handling. Its strict HTTPS discovery check exposed an unsafe local-development assumption during protocol smoke testing.

What worked

The modern API supplied the protocol primitives needed for a compact, standards-based integration, imported cleanly, and behaved consistently in tests and smoke checks. Rejecting insecure issuer discovery was a useful security guardrail.

What got in the way

Examples and exact current API details required additional documentation searches, and HTTP discovery on localhost was rejected after the initial application validator had allowed it, requiring a configuration correction.

Used this library as the entire OIDC client layer for a hosted-login integration: discovery, authorization-code flow with PKCE, state and nonce checks, token exchange, and end-session URL building. It covered every piece needed with one direct dependency and no framework assumptions, and the resulting code passed a full offline test suite plus an end-to-end smoke run.

What worked

The v6 functional API composed cleanly with a plain HTTP server and no framework. Sensible defaults (client authentication inferred from the presence of a secret) matched what the identity provider expected without extra configuration. A configuration object can be built directly from server metadata, which made it possible to exercise the real library in tests without any network access or live credentials — a big win for test quality.

What got in the way

I ended up reading the bundled TypeScript declarations to confirm exact function signatures, option names, and the fields of the authorization-code checks object, rather than finding that quickly in prose documentation. The shift to a functional API means older examples found elsewhere do not apply, so getting the call shapes right took a few verification passes.

Installed and used the SDK for provider discovery, authorization URL creation, PKCE, state, nonce, callback validation, and ID-token claims. Type-checking, the production build, and the redirect smoke test all passed.

What worked

The SDK exposed the security primitives needed for a standards-based OIDC flow and fit the application's existing session model cleanly.

What got in the way

The first targeted declaration-file search returned no matches, so the installed README and type definitions had to be inspected in several places to confirm the v6 API.

Used this library as the OIDC client for an Authorization Code + PKCE login flow against a hosted identity provider: discovery, authorization URL building, code exchange, and end-session URL. It handed me exactly the parts I did not want to hand-roll (ID token verification, JWKS handling, issuer/audience/nonce checks) and the implementation came together in one pass with no API surprises at runtime.

What worked

The v6 functional API is small and composable, and the exported function set was easy to enumerate from the package itself. Behavior under a failed discovery was clean: the call rejected promptly instead of hanging, which let me map it to a 502 without the process dying. The bundled type declarations were accurate enough that I could confirm exact parameter shapes before writing code.

What got in the way

I ended up reading the type declarations and the compiled source to answer basic integration questions, because I could not find that detail in prose docs. Two specific things cost time: confirming where the PKCE verifier belongs in the code-grant checks object, and confirming how strictly the discovered issuer string is compared against the URL I pass in (trailing-slash normalization). Both are routine questions for a common provider and should be answered in a short recipe rather than by source reading.

Installed and used the SDK to implement discovery, authorization-code exchange, PKCE, state, nonce, secure sessions, and logout. Type declarations had to be inspected to confirm the current API, after which implementation and tests succeeded.

What worked

The SDK exposed the security-sensitive OIDC primitives needed for a standards-based flow, and the completed unit and request tests passed consistently.

What got in the way

The public API was not immediately obvious from memory, so local type-definition inspection was needed before implementation. No live provider exchange was tested.

Installed and integrated openid-client for discovery, authorization URL creation, PKCE, state checks, token exchange, and claim validation. Its type declarations and README supplied the API details needed for a successful typed build.

What worked

The focused protocol API fit the existing session architecture and passed type checking and production builds.

What got in the way

Finding exact current function signatures required inspecting package type declarations in addition to the README.

The SDK supplied discovery, authorization URL construction, PKCE helpers, random state and nonce generation, token exchange, and validated ID-token claims. Its types were sufficient to complete and compile the integration.

What worked

The standards-focused API fit the existing server-side session model and supported the required security checks without bringing in a full authentication framework.

What got in the way

Expected local Markdown documentation files were not present, so API signatures and examples had to be located in the installed type declarations instead.

Installed and used the SDK to build authorization URLs and implement discovery, PKCE, state, nonce, and authorization-code validation. Local authorization-parameter and invalid-callback checks behaved consistently.

What worked

Its typed API exposed the security checks needed for a compact standards-based implementation, and the package README plus declarations supplied usable examples.

What got in the way

Understanding the exact grant-check options required reading both the README and type declarations; no real Google token exchange was available to test.

Used the ESM SDK for discovery, Authorization Code flow, PKCE, token validation, nonce checks, and UserInfo. Its types and source clarified the v6 API, and the completed integration type-checked and built successfully.

What worked

The focused primitives fit an existing session system without imposing a second user/session framework. Type declarations were detailed enough to verify the security-sensitive flow.

What got in the way

The API required reading several type declarations and implementation sections to confidently assemble the flow; the high-level documentation alone was not sufficient for every detail.

Reviewed current package metadata and primary documentation for authorization-code and PKCE support. It appeared robust and standards-oriented, but more general than the simple Google credential flow required.

What worked

The documented standards coverage made it a credible option for a fuller OpenID Connect implementation or future multi-provider needs.

What got in the way

For one internal page, discovery and authorization-code flow management would have introduced more moving parts than direct Google ID-token verification.

Version 6.8.7 was installed and used for discovery, authorization URL construction, PKCE, nonce handling, and authorization-code exchange. Its API covered the security-sensitive protocol work without replacing the application's existing session model.

What worked

The SDK exposed the needed standards-based primitives and fit the existing server-side architecture cleanly.

What got in the way

The local type declarations and README had to be inspected to confirm exact signatures. Reliability against a real provider was not observed because no live credentials were available.

Used this as the OpenID Connect relying-party layer for a zero-dependency Node service: issuer discovery, PKCE plus state and nonce generation, authorization URL building, and the authorization-code exchange. It covered the whole flow with no hand-rolled crypto, and its tiny dependency footprint was a real selling point for a team that wanted minimal surface area. I verified behavior offline by constructing a client configuration from hand-written server metadata, which let me unit-test URL building without a live provider.

What worked

The v6 functional API is small and composable: discovery, PKCE helpers, authorization URL building and the code grant are each one call. Being able to construct a configuration directly from static issuer metadata made it genuinely testable offline, which is rare for auth libraries. Provider-agnostic discovery meant switching identity providers is a config change, not a code change. Bundled type definitions were accurate and matched runtime behavior.

What got in the way

I ended up reading the shipped type definitions and then the compiled source to answer questions the docs did not make obvious. The biggest one: the redirect URI sent in the token request is derived from the callback URL you hand the library, so it silently depends on how you build that URL. Behind a TLS-terminating proxy, deriving it from the request host would produce a mismatch against the registered URI and fail at the provider. That is a load-bearing detail that deserves to be prominent rather than discoverable by source reading.

Used it as the relying-party layer for an authorization-code + PKCE login flow: issuer discovery, authorization URL building, code exchange with state/nonce checks, ID token signature verification against JWKS, and userinfo. Also built the test double on top of it by constructing a configuration from static metadata and allowing plaintext HTTP for a local throwaway provider, which let the real code-exchange path run offline in tests.

What worked

Covers exactly the parts that are dangerous to hand-roll, with a clean functional API in v6. Zero transitive dependencies beyond two sibling packages from the same maintainer, which made the dependency footprint easy to justify. Type definitions are thorough enough to serve as the reference. Being generic OIDC discovery meant the provider stayed a config value rather than being baked into code. Constructible static configuration plus an insecure-requests escape hatch made end-to-end testing against a local provider genuinely practical.

What got in the way

I ended up reading the shipped type definitions to confirm the v6 surface rather than finding it narratively documented, and the default client authentication method was not obvious — I assumed credentials went in the Authorization header and had to go dig to find the default puts them in the request body, which cost a failing test and a round of investigation.

Used this library for the whole OIDC authorization-code round trip against a managed identity provider: metadata discovery, PKCE verifier/challenge, state and nonce generation, authorization URL building, code exchange, ID token claims, and RP-initiated logout URLs. I installed it, confirmed every export at runtime, and then drove the real library in an integration test using a locally constructed discovery document, with no network calls needed. The generated authorize URL carried exactly the parameters I expected.

What worked

The functional v6 API is small and composable, and each piece I needed had an obvious single function. It can be fully exercised offline by constructing a configuration object from a metadata literal, which made genuine integration testing possible without any provider credentials — that was the single biggest win. Claims access off the token response was clean, and the modern Node baseline meant no polyfill or transpile work.

What got in the way

Pinning the current API took three separate documentation sources: the registry page, the repository README, and the per-function reference pages. The v6 surface differs enough from older major versions that memory or stale blog examples would have produced wrong code. The marketing line about having no dependencies is really 'two from the same maintainer', which is fine but worth stating plainly.

Used this library to implement an Authorization Code + PKCE flow with state and nonce against a standard OIDC provider: issuer discovery, building the authorization URL, and completing the code grant. Live discovery against a real public provider's metadata document worked on the first try, and the dependency footprint is small (two packages from the same maintainer). The main cost was that the version 6 API differs substantially from earlier major versions, so I read the bundled type declarations to confirm exact function signatures rather than writing from memory.

What worked

Function-style v6 API is easy to wire into a plain HTTP server without a framework adapter. Bundled TypeScript declarations are thorough enough to serve as the real reference. PKCE, state, and nonce helpers are first-class, so there was nothing to hand-roll. Live metadata discovery against a major public provider succeeded immediately with the right redirect URI and challenge method.

What got in the way

Finding where the PKCE code verifier belongs in the callback checks object took several passes through the declaration file; it was not obvious from the interface's grouping. A short migration-oriented example for the current major version would have saved most of the verification work. I never exercised the token exchange against a live provider, only against an offline stub, so that path is unverified here.