migration: openid-client and jose migration by aks96 · Pull Request #785 · auth0/express-openid-connect

aks96 · 2026-02-09T12:39:50Z

Summary

Upgrades openid-client from v4 to v6 and jose from v2 to v6. These are now ESM-only packages, which drives the Node.js version requirement change.
The core middleware API, session handling, and all authentication methods remain unchanged.

Breaking Changes

See V3_MIGRATION_GUIDE.md for before/after examples and migration steps for each change.

Node.js version — requires ^20.19.0 || ^22.12.0 || >= 23.0.0
httpAgent config removed — replaced by customFetch. Passing httpAgent throws at startup.
clientAssertionSigningAlg now required — the implicit RS256 default has been removed. Required when clientAssertionSigningKey is a PEM, Buffer, KeyObject, or JWK without an alg property.
ES256K and EdDSA removed from valid clientAssertionSigningAlg values. Use Ed25519 instead of EdDSA. ES256K has no replacement.
afterCallback behavior change — req.oidc now reflects the incoming user's new tokens during the callback, not the previous session state.
Session cookie dropped on streaming responses — in v2, the session cookie was injected just before headers were flushed, so it worked even on streaming responses. In v3, the cookie is written at res.end() time instead. If your route calls res.write(), res.flushHeaders(), or res.writeHead() before the response ends (e.g. SSE, chunked responses), the session cookie will be silently skipped. If you rely on token rotation, avoid using it on streaming routes.
clientAssertionSigningKey type updated — if you use TypeScript, the accepted type for clientAssertionSigningKey has changed to align with jose v6 and the Web Crypto API. In practice, all previously supported key formats (PEM string, Buffer, KeyObject, JWK) still work at runtime — only the TypeScript type definition has changed

Testing

Manual testing against a real Auth0 tenant

Scenario	Flow
Basic login flow	Discovery, token exchange, callback URL handling, session cookie written correctly
`customFetch` wiring	Called for both discovery and token endpoints, confirmed via logging
`httpAgent` rejection	Throws `TypeError: "httpAgent" is not allowed` at startup before the app boots
Private key JWT with PEM + `clientAssertionSigningAlg: 'RS256'`	Full login succeeds using signed `client_assertion` JWT
Private key JWT without `clientAssertionSigningAlg`	Throws at startup
`afterCallback` new behavior	`req.oidc.user` reflects the incoming user's tokens, confirmed `sub` matches the new ID token
Streaming response (`res.writeHead` before `res.end`)	No crash, session cookie silently skipped.

Unit tests

Unit tests have been updated to reflect the new API and behaviour.

End-to-end tests

The existing end-to-end test suite covers the full login/logout flow, token refresh, backchannel logout (basic, re-login after logout, custom genid, custom query store), and custom session store scenarios using a local OIDC provider.

…ientv6

nandan-bhat · 2026-04-29T11:07:50Z

-      const { client, issuer } = await getClient(config);
-      const redirectUri = options.redirectUri || this.getRedirectUri();
+      const { configuration } = await getClient(config);
+      // Note: In openid-client v6, redirect_uri is automatically extracted from the


redirect_uri is still part of the public API and the typedocs still show res.oidc.callback({ redirectUri: ... }).

If we now always derive the redirect URI from the current request URL, apps with custom callback routes or multiple domains may send a different redirect_uri to the token endpoint than the one used during login.

If this is intentional, can we call it out as a breaking change and update the types/docs ?

nandan-bhat · 2026-04-29T11:19:12Z

+        // Build host with port if needed
+        const host = needsPort ? `${hostname}:${port}` : hostname;
+
+        const currentUrl = new URL(`${protocol}://${host}${req.originalUrl}`);


IMO, we should not drop options.redirectUri support here. Even though openid-client v6 can infer the redirect_uri from the URL passed to authorizationCodeGrant(), this SDK can still decide which URL to pass in.

To preserve the existing express-openid-connect API, we should use options.redirectUri when it is supplied, and only infer the callback URL from the request when it is not.

Otherwise, existing apps that rely on res.oidc.callback({ redirectUri }) may break silently, even though the option is still documented and typed.

yes, I completely agree, the support for options.redirectUri should not have been dropped. I already pointed this out earlier, I guess this got missed to address - #785 (comment)
pre-v6, the redirectUri was constructed from either options.redirectUri or using getRedirectUri method and explicitly passed to openid-client's callback method.
Have restored the same behavior.

Updated:

Removed the comment that said options.redirectUri is no longer used

Added callbackUrl construction after currentUrl is built, restoring the options.redirectUri || this.getRedirectUri() fallback chain as earlier.

The request obj passed to oidcClient has this callcackUrl instead of original request's url

nandan-bhat · 2026-04-29T11:28:48Z

+
    if (isCustomStore) {
      const id = existingSessionValue || (await generateId(req));



Can we add coverage for responses that flush headers before res.end() ?. Since session cookies are now written from the res.end wrapper, setCookie() may skip writing the cookie when res.headersSent is already true.

This can happen for streaming responses or routes that call res.write() before res.end(). Previously, on-headers wrote cookies right before headers were sent, so this may be a behavior change where session updates are silently lost.

Right, this is a limitation introduced by removing on-headers. It can all be attributed to jose-v6 async encryption, which makes our setCookie async too. on-headers only supports synchronous callbacks, so it can no longer be used to write the cookie right before headers are flushed.

I've made the failure explicit with a debug log when headersSent is already true, covering not just streaming responses but any scenario where headers are flushed early (res.write(), res.writeHead(), res.flushHeaders(), res.sendFile()).

As per your suggestion I've also added a test that properly documents and asserts this behavior.

nandan-bhat · 2026-04-29T11:32:21Z

+      );
+    }
+
+    return fetch(fetchUrl, {


httpAgent is still listed as a public configuration option, but this new fetch implementation doesn’t seem to use it anymore. Some users might depend on it for things like proxies, custom TLS settings, or controlling network access.

Can we either make sure httpAgent is used in this new fetch logic, or clearly document this as a breaking change and update the types and docs?

yes, support for passing httpAgent has been removed.

The core issue is that httpAgent worked because got (the HTTP library openid-client v4 used internally) had a first-class concept of agents, we could hand it an http.Agent or https.Agent and it would use that for every connection it made.
openid-client v6 replaced got with native fetch, and fetch simply has no equivalent concept, there's no way to pass a Node.js http.Agent into a fetch() call. The two APIs model transport-level control completely differently, so the old option can't be mapped across.

Update:
Reference - PR#787

Instead, we've exposed customFetch as the escape hatch. It gives consumers full control over the underlying HTTP behaviour, whether that's routing through a proxy, pinning a custom TLS certificate, adding retry logic, or just logging outbound requests for debugging. The SDK wraps whatever function is provided to inject required headers (User-Agent, telemetry) before the call goes out, so SDK concerns stay intact regardless of what the consumer does underneath. For the proxy case specifically, undici ships with Node.js 18+ so no extra dependency is needed

On the type side, removed httpAgent from index.d.ts (along with the HttpAgent/HttpsAgent imports) and typed customFetch as typeof fetch, This is broad enough to be compatible with undici and other fetch-compatible implementations.

Also added Example-13 to EXAMPLES.md showing the undici ProxyAgent pattern end-to-end.

For test coverage, added two behavioural tests, one asserting the provided function is actually invoked during discovery, and another confirming the SDK's header decoration still runs before the call reaches the consumer's function.

nandan-bhat · 2026-04-29T11:34:58Z

    "joi": "^17.13.3",
-    "jose": "^2.0.7",
+    "jose": "^6.1.3",
    "on-headers": "^1.1.0",


Since this PR no longer uses on-headers, can we remove it from dependencies ?

If we decide to restore on-headers to preserve the old session-cookie timing behavior, then it should stay. Otherwise this looks like a stale dependency after the session persistence refactor.

Removed it from dep list.
I know it was perfect at setting the cookie at right moment but don't think we can bring it back, as it expects a synchronous callback and our setCookie method changed to async.

nandan-bhat · 2026-04-29T11:40:50Z

    });

-    it('should timeout for delay > httpTimeout', async function () {
+    it.skip('should timeout for delay > httpTimeout', async function () {


Can we avoid skipping this test ? httpTimeout is still a public config option, so we should keep coverage that requests actually fail when they exceed the configured timeout.

If timeout behavior changed with fetch/openid-client v6, we should update the assertion to match the new error shape rather than skipping the test entirely.

I've re enabled and updated the test suite client respects httpTimeout configuration to better cover for all 3 httpTimeout scenarios.

nandan-bhat · 2026-04-29T11:42:10Z

  });

-  describe('client respects clientAssertionSigningAlg configuration', function () {
+  describe.skip('client respects clientAssertionSigningAlg configuration', function () {


Can we avoid skipping this test suite ? clientAssertionSigningAlg is still a public option, and this PR changes the private key JWT implementation during the openid-client v6 migration.

We should keep coverage that the configured signing algorithm is actually used, even if the test needs to be rewritten around the v6 grant APIs.

I've re enabled this test suite and updated the tests to cover -
Test 1: should use RS256 as the default signing algorithm in the client assertion
Test 2: should use the configured signing algorithm in the client assertion
Test 3: should fail when signing algorithm is incompatible with the key type

nandan-bhat · 2026-04-29T11:44:05Z

  });

-  describe('client respects httpAgent configuration', function () {
+  describe.skip('client respects httpAgent configuration', function () {


Can we avoid skipping this test suite ?. httpAgent is still a public config option, but this PR no longer appears to pass it into the HTTP layer.

If httpAgent support is intentionally removed because of the fetch migration, we should document it as a breaking change and update the public types/docs.

Otherwise, this test should be rewritten to verify the new implementation still honors httpAgent.

nandan-bhat · 2026-04-29T11:47:44Z

      },
      "engines": {
-        "node": "^10.19.0 || >=12.0.0 < 13 || >=13.7.0 < 14 || >= 14.2.0"
+        "node": ">=20.0.0"


Can we keep this in sync with package.json ?

The package declares Node support as ^20.19.0 || ^22.12.0 || >= 23.0.0, but the lockfile root package still says >=20.0.0. Take a look at this:

express-openid-connect/package.json

Line 76 in bfe775e

"node": "^20.19.0 || ^22.12.0 || >= 23.0.0"

Since the migration guide says the exact minimum versions matter for require(ESM) support, the lockfile should reflect the same engine range to avoid confusion.

Addressed it for now,
But we will probably plan the removal of package lock file after after this in a separate PR.

nandan-bhat · 2026-04-29T11:51:46Z

Refer to https://github.com/auth0/express-openid-connect/pull/785/changes#r3160619280

… be passed to openid-client@6 in callback handler

…e persisted. Add test coverage for these scenarios

…or all the openid-client's netowrk calls

…config reference

…uite

… KeyObject, or JWK without an alg property

… guide

This PR needs further review. I am dismissing my approval.

nandan-bhat · 2026-05-12T06:49:07Z

+  const issuerRespTypes = Array.isArray(serverMetadata.response_types_supported)
+    ? serverMetadata.response_types_supported
    : [];
  issuerRespTypes.map(sortSpaceDelimitedString);


.map() returns a new array and does not change issuerRespTypes. Doesn't this mean the comparison on line 186 always uses the original unsorted values ? For example, wouldn't "code id_token" fail to match "id_token code" ?

Should this be:

const sortedRespTypes = issuerRespTypes.map(sortSpaceDelimitedString); if (!sortedRespTypes.includes(configRespType)) {

yes, the comparison should have been made on sortedRespTypes result.
Updated.

nandan-bhat · 2026-05-12T06:53:01Z

   * this property will be required.
   */
  clientAssertionSigningAlg?:
    | 'RS256'


The TypeScript type still allows 'ES256K' and 'EdDSA', but the Joi schema in

express-openid-connect/lib/config.js

Lines 316 to 328 in be90b7d

clientAssertionSigningAlg: Joi.string()

.valid(

'RS256',

'RS384',

'RS512',

'PS256',

'PS384',

'PS512',

'ES256',

'ES384',

'ES512',

'Ed25519',

)

rejects them at runtime.

Should we update the type to match the new valid set ('Ed25519' instead of 'EdDSA', and remove 'ES256K') ?

yes, there was a mismatch between Joi schema for clientAssertionSigningAlg and type def file.
This was mistakenly left unchecked while determining breaking changes.
Updated the index.d.ts to reflect the same.

cschetan77 · 2026-05-12T08:26:15Z

+    this.token_type =
+      tokenSet.token_type?.toLowerCase() === 'bearer'
+        ? 'Bearer'
+        : tokenSet.token_type;
+


token_type normalization already happened during session write time. This is redundant.

…teed to provide crypto.hkdfSync

…orwareded info

aks96 added 2 commits February 9, 2026 16:28

migration: openid-client and jose migration

6302c75

migration guide

fd04c9e

aks96 requested a review from a team as a code owner February 9, 2026 12:39

github-advanced-security AI found potential problems Feb 9, 2026

View reviewed changes

Comment thread test/client.tests.js Fixed

Comment thread test/client.tests.js Fixed

aks96 added 4 commits February 9, 2026 20:18

version fix and migration update

27963f2

CI fix

4e95839

CI fix

9c63bd8

Migration guide

3d99deb

cschetan77 reviewed Feb 11, 2026

View reviewed changes

Comment thread V3_MIGRATION_GUIDE.md

panva reviewed Feb 11, 2026

View reviewed changes

Comment thread lib/context.js Outdated

panva reviewed Feb 11, 2026

View reviewed changes

Comment thread lib/context.js Outdated

cschetan77 requested changes Mar 31, 2026

View reviewed changes

Comment thread lib/client.js

Comment thread lib/client.js Outdated

Comment thread lib/client.js Outdated

Comment thread lib/client.js Outdated

Comment thread lib/client.js Outdated

cschetan77 reviewed Apr 5, 2026

View reviewed changes

Comment thread lib/crypto.js Outdated

Comment thread lib/appSession.js

addressed comments

56b8799

aks96 force-pushed the migration/openid-clientv6 branch from 32b378e to 56b8799 Compare April 7, 2026 18:23

aks96 and others added 3 commits April 7, 2026 23:57

Merge branch 'master' into migration/openid-clientv6

796d59f

fix failed actions

51ad64c

fix failed actions

f1db455

aks96 requested a review from cschetan77 April 8, 2026 06:05

cschetan77 requested changes Apr 13, 2026

View reviewed changes

Comment thread lib/appSession.js Outdated

Comment thread lib/appSession.js Outdated

Comment thread lib/appSession.js

aks96 added 2 commits April 17, 2026 13:43

Merge remote-tracking branch 'origin/master' into migration/openid-cl…

119567f

…ientv6

comments addressed

22a7bcb

cschetan77 requested changes Apr 23, 2026

View reviewed changes

Comment thread lib/context.js Outdated

Comment thread lib/context.js Outdated

Comment thread lib/context.js Outdated

cschetan77 requested changes Apr 23, 2026

View reviewed changes

Comment thread lib/context.js Outdated

Comment thread lib/context.js Outdated

fixed edge cases

bfe775e

nandan-bhat reviewed Apr 29, 2026

View reviewed changes

cschetan77 added 4 commits May 3, 2026 19:29

construct callbackUrl explicitly from SDK's configured redirectUri to…

a4f79e0

… be passed to openid-client@6 in callback handler

Add debug if headers were already sent and session cookie could not b…

0318dea

…e persisted. Add test coverage for these scenarios

Removing support for httpAgent SDK config and providing customFetch f…

c6711e1

…or all the openid-client's netowrk calls

remove on-headers stale dep

621dcc9

cschetan77 added 9 commits May 4, 2026 18:06

Hoist RemoteJWKSet instance creation to module scope and cache it on …

40cae2f

…config reference

enable client respects clientAssertionSigningAlg configuration test s…

331a8e3

…uite

Update client respects httpTimeout configuration test suite

dea71ff

Sync package lock

6c7a7a5

Account for mounted app scenarios

20a2a01

clientAssertionSigningAlg now required for any app using PEM, Buffer,…

5221f75

… KeyObject, or JWK without an alg property

Update breaking changes in V3_MIGRATION_GUIDE

6d16d7a

update node ver in README and put a note for allow insecure requests

628954a

update clientAssertionSigningKey breaking change section in migration…

be90b7d

… guide

This comment was marked as off-topic.

Sign in to view

nandan-bhat previously approved these changes May 12, 2026

View reviewed changes

nandan-bhat reviewed May 12, 2026

View reviewed changes

cschetan77 added 2 commits May 12, 2026 12:38

fix: capture sorted response types before issuer compatibility check

0236ae7

fix: clientAssertionSigningAlg in type def file to match with joi schema

63855bc

cschetan77 reviewed May 12, 2026

View reviewed changes

cschetan77 added 5 commits May 12, 2026 14:01

fix: remove redundant normalization from TokenSet class

12b3350

fix: remove futoin-hkdf dep and it's usage, since node >=20 is guaren…

6159f01

…teed to provide crypto.hkdfSync

fix: fix: track discovery cache expiry per config instead of globally

f1cf167

fix: handle IPv6 address while extracting port from reverse proxy's f…

4205d24

…orwareded info

gh workflow unit: add 20.x, 22.x and 24.x to test matrix

a354554

nandan-bhat approved these changes May 12, 2026

View reviewed changes

cschetan77 approved these changes May 12, 2026

View reviewed changes

cschetan77 merged commit 076fb82 into master May 12, 2026
23 of 25 checks passed

cschetan77 deleted the migration/openid-clientv6 branch May 12, 2026 16:20

This was referenced May 12, 2026

feature: migration of openid-client from v4 to v6 #735

Closed

chore: update typedoc compiler options for ESM compatibility #819

Merged

Release v3.0.0 #820

Merged

cschetan77 mentioned this pull request Jun 16, 2026

feat: Test infrastructure for v6 #760

Closed


		if (isCustomStore) {
		const id = existingSessionValue \|\| (await generateId(req));

	clientAssertionSigningAlg: Joi.string()
	.valid(
	'RS256',
	'RS384',
	'RS512',
	'PS256',
	'PS384',
	'PS512',
	'ES256',
	'ES384',
	'ES512',
	'Ed25519',
	)

Uh oh!

Conversation

aks96 commented Feb 9, 2026 • edited by cschetan77 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking Changes

Testing

Manual testing against a real Auth0 tenant

Unit tests

End-to-end tests

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as off-topic.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cschetan77 May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

aks96 commented Feb 9, 2026 •

edited by cschetan77

Loading

cschetan77 May 12, 2026 •

edited

Loading