ep_openid_connect 3.0.29 → 3.0.31

package/README.md

@@ -60,6 +60,14 @@ Etherpad's `requireAuthentication` setting must be `true`.
 * `base_url` (required): The public base Etherpad URL. When registering Etherpad
   with your identity provider, the redirect URL (a.k.a. callback URL) is this
   base URL plus `/ep_openid_connect/callback`.
+* `ca` (optional): Custom Certificate Authority bundle for verifying TLS
+  connections to the identity provider — useful when the provider's
+  certificate is signed by a private or internal CA rather than a public
+  one. The value can be either a filesystem path to a PEM file or the PEM
+  content itself (recognised by a leading `-----BEGIN`). If you control the
+  Node startup environment you may instead set the
+  [`NODE_EXTRA_CA_CERTS`](https://nodejs.org/api/cli.html#node_extra_ca_certsfile)
+  environment variable, which has the same effect for the whole process.
 * `scope` (optional; defaults to `["openid"]`): List of OAuth2 scope strings.
 * `prohibited_usernames` (optional; defaults to `["admin", "guest"]`): List of
   strings that will trigger an authentication error if any match the `sub`

package/index.js

@@ -1,6 +1,8 @@
 'use strict';
 
 const Ajv = require('ajv/dist/jtd');
+const fs = require('fs');
+const undici = require('undici');
 const {URL} = require('url');
 
 let logger = {};
@@ -29,6 +31,14 @@ const validSettings = new Ajv().compile({
     client_secret: {type: 'string'},
   },
   optionalProperties: {
+    // Path to a PEM-encoded certificate authority bundle (or the PEM
+    // content itself, recognised by a leading `-----BEGIN`). Used to verify
+    // TLS connections to identity providers that present a certificate
+    // signed by a private/internal CA. Operators who control the Node
+    // process can equivalently set NODE_EXTRA_CA_CERTS — this option is for
+    // settings.json-driven deployments where touching the Node startup
+    // command isn't an option.
+    ca: {type: 'string'},
     issuer: {type: 'string'},
     issuer_metadata: {},
     prohibited_usernames: {elements: {type: 'string'}},
@@ -82,6 +92,24 @@ const isHttp = (urlString) => {
   }
 };
 
+// Load a CA bundle from either a path or an inline PEM string. Returns the
+// PEM content as a string, or `null` for an empty/missing setting.
+// Exported for unit testing.
+const loadCaBundle = (caSetting) => {
+  if (typeof caSetting !== 'string' || !caSetting) return null;
+  if (caSetting.startsWith('-----BEGIN ')) return caSetting;
+  return fs.readFileSync(caSetting, 'utf8');
+};
+
+// Build a `fetch` implementation that trusts the given PEM-encoded CA
+// bundle, suitable for assigning to `config[oidc.customFetch]`. Each call
+// creates a single shared undici dispatcher so HTTP connections to the IdP
+// can be reused across discovery, token-exchange, and userinfo calls.
+const buildCustomFetch = (caBundle) => {
+  const dispatcher = new undici.Agent({connect: {ca: caBundle}});
+  return (url, options) => undici.fetch(url, {...options, dispatcher});
+};
+
 // Pick the token endpoint auth method to use, given the IdP's advertised
 // `token_endpoint_auth_methods_supported` and any explicit override from
 // settings. Pure; exported for unit testing.
@@ -116,7 +144,7 @@ const clientAuthFor = (method, secret) => {
   }
 };
 
-const fetchServerMetadata = async (issuerUrl, clientId) => {
+const fetchServerMetadata = async (issuerUrl, clientId, customFetch) => {
   const url = new URL(issuerUrl);
   // https://openid.net/specs/openid-connect-discovery-1_0.html#IssuerDiscovery says that the URI
   // must not have query or fragment components.
@@ -128,16 +156,22 @@ const fetchServerMetadata = async (issuerUrl, clientId) => {
   }
   // openid-client@6 rejects http:// issuers by default; opt back in for
   // localhost / private-network providers (matches v5 behaviour).
-  const options = url.protocol === 'http:'
-    ? {execute: [oidc.allowInsecureRequests]}
-    : undefined;
+  const options = {};
+  if (url.protocol === 'http:') options.execute = [oidc.allowInsecureRequests];
+  // `customFetch` must be set on the options bag (not on `execute`) so that
+  // discovery's OWN HTTPS request to /.well-known/openid-configuration uses
+  // it. `execute` callbacks only run AFTER discovery finishes.
+  if (customFetch != null) options[oidc.customFetch] = customFetch;
   try {
     // Discovery fetches the .well-known/openid-configuration document. The
     // clientAuthentication argument is irrelevant for that HTTP request — it
     // only matters when the Configuration is later used to exchange a code
     // for a token — so we can pass `undefined` here and bind the real method
     // below once we know what the IdP supports.
-    const tempConfig = await oidc.discovery(url, clientId, undefined, undefined, options);
+    const tempConfig = await oidc.discovery(
+        url, clientId, undefined, undefined,
+        Object.keys(options).length || Object.getOwnPropertySymbols(options).length
+          ? options : undefined);
     return tempConfig.serverMetadata();
   } catch (err) {
     // The URL used to get the issuer metadata doesn't exactly follow RFC 8615; see:
@@ -156,13 +190,22 @@ const fetchServerMetadata = async (issuerUrl, clientId) => {
 };
 
 const buildConfig = async (settings) => {
+  // If the operator gave us a custom CA bundle, build a fetch that trusts
+  // it; otherwise leave the default fetch in place. We deliberately build
+  // the customFetch BEFORE discovery so the discovery HTTP call itself
+  // uses the trusted CA — the configured IdP is typically the same host
+  // that serves the well-known document.
+  const caBundle = loadCaBundle(settings.ca);
+  const customFetch = caBundle ? buildCustomFetch(caBundle) : null;
+
   // Resolve the server metadata (either via discovery or from the inline
   // `issuer_metadata` blob) BEFORE choosing an auth method, so we can pick
   // one the IdP actually advertises.
   let serverMetadata;
   let phaseLog;
   if (settings.issuer) {
-    serverMetadata = await fetchServerMetadata(settings.issuer, settings.client_id);
+    serverMetadata =
+        await fetchServerMetadata(settings.issuer, settings.client_id, customFetch);
     phaseLog = 'OpenID Connect Discovery complete.';
   } else {
     serverMetadata = settings.issuer_metadata;
@@ -177,8 +220,10 @@ const buildConfig = async (settings) => {
   if (isHttp(serverMetadata && serverMetadata.issuer)) {
     oidc.allowInsecureRequests(config);
   }
+  if (customFetch != null) config[oidc.customFetch] = customFetch;
   const source = settings.token_endpoint_auth_method ? 'configured' : 'auto-picked';
-  logger.info(`${phaseLog} Token endpoint auth method: ${method} (${source}).`);
+  logger.info(`${phaseLog} Token endpoint auth method: ${method} (${source})` +
+      (caBundle ? ' with custom CA bundle.' : '.'));
   return config;
 };
 
@@ -378,6 +423,7 @@ exports.preAuthorize = (hookName, {req}) => {
 exports.exportedForTestingOnly = {
   callbackUrlFromRequest,
   defaultSettings,
+  loadCaBundle,
   pickAuthMethod,
   validSettings,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ep_openid_connect",
-  "version": "3.0.29",
+  "version": "3.0.31",
   "description": "Etherpad plugin to authenticate users against an OpenID Connect provider.",
   "main": "index.js",
   "repository": {
@@ -24,12 +24,13 @@
   "homepage": "https://github.com/ether/ep_openid_connect#readme",
   "dependencies": {
     "ajv": "^8.20.0",
-    "openid-client": "^6.8.4"
+    "openid-client": "^6.8.4",
+    "undici": "^8.3.0"
   },
   "devDependencies": {
     "eslint": "^8.57.1",
     "eslint-config-etherpad": "^4.0.5",
-    "oidc-provider": "^9.8.3",
+    "oidc-provider": "^9.8.4",
     "supertest": "^6.3.4",
     "typescript": "^6.0.3"
   },

package/static/tests/backend/specs/custom_ca.js

@@ -0,0 +1,243 @@
+'use strict';
+
+// End-to-end coverage for the `ca` setting: stand up an HTTPS-fronted OIDC
+// provider with a self-signed certificate, point the plugin at it, and
+// confirm a real login completes when the matching CA is configured (and
+// fails when it isn't). This is the only sound way to prove that the
+// custom-fetch wiring actually replaces Node's default fetch — a unit test
+// that just checks `config[customFetch]` is set would miss the case where
+// undici and openid-client disagree on the option shape.
+
+const Provider = require('oidc-provider').default;
+const MemoryAdapter = require('oidc-provider/lib/adapters/memory_adapter').default;
+const assert = require('assert').strict;
+const child_process = require('child_process');
+const common = require('ep_etherpad-lite/tests/backend/common');
+const epOpenidConnect = require('../../../../index');
+const fs = require('fs');
+const https = require('https');
+const os = require('os');
+const path = require('path');
+const settings = require('ep_etherpad-lite/node/utils/Settings');
+const util = require('util');
+
+// Generate a self-signed cert valid for localhost via the OpenSSL CLI.
+// Using a CLI avoids pulling in `selfsigned`+`@peculiar/x509`+`node-forge`
+// as devDependencies just for one test, and `openssl` is available on every
+// CI runner and dev machine.
+const generateSelfSignedCert = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ep-openid-cert-'));
+  const keyPath = path.join(dir, 'key.pem');
+  const certPath = path.join(dir, 'cert.pem');
+  child_process.execFileSync('openssl', [
+    'req', '-x509',
+    '-newkey', 'rsa:2048',
+    '-nodes',
+    '-keyout', keyPath,
+    '-out', certPath,
+    '-days', '1',
+    '-subj', '/CN=localhost',
+    '-addext', 'subjectAltName=DNS:localhost,IP:127.0.0.1',
+  ], {stdio: 'pipe'});
+  return {
+    dir,
+    key: fs.readFileSync(keyPath, 'utf8'),
+    cert: fs.readFileSync(certPath, 'utf8'),
+    keyPath,
+    certPath,
+  };
+};
+
+const httpsListen = util.promisify(https.Server.prototype.listen);
+const httpsClose = util.promisify(https.Server.prototype.close);
+
+// No-op subclass mirrors the helper in ../oidc-provider.js — silences the
+// MemoryAdapter "not for production" warning.
+class Adapter extends MemoryAdapter {}
+
+// Minimal HTTPS-fronted OIDC provider for the CA-trust test. Mirrors the
+// happy path of static/tests/backend/oidc-provider.js but listens on TLS.
+class HttpsOidcProvider {
+  async start({clients, tls}) {
+    this._server = https.createServer(tls);
+    await httpsListen.call(this._server, 0, 'localhost');
+    this.issuer = `https://localhost:${this._server.address().port}/`;
+    this._provider = new Provider(this.issuer, {
+      adapter: Adapter,
+      claims: {etherpad: ['name']},
+      clients,
+      cookies: {keys: [common.randomString()]},
+      features: {devInteractions: {enabled: false}},
+      findAccount: async (ctx, sub) => ({
+        accountId: sub,
+        claims: async () => ({sub, name: 'Firstname Lastname'}),
+      }),
+      jwks: {keys: [{
+        kty: 'EC',
+        crv: 'P-256',
+        d: 'K9xfPv773dZR22TVUB80xouzdF7qCg5cWjPjkHyv7Ws',
+        x: 'FWZ9rSkLt6Dx9E3pxLybhdM6xgR5obGsj5_pqmnz5J4',
+        y: '_n8G69C-A2Xl4xUW2lF0i8ZGZnk_KPYrhv4GbTGu5G4',
+        use: 'sig',
+      }]},
+      ttl: {AccessToken: 3600, Grant: 3600, IdToken: 3600, Interaction: 3600, Session: 3600},
+    });
+    this._server.on('request', this._provider.callback());
+    // Same shortcut as the HTTP helper: skip past the login + consent UI by
+    // accepting the username in a query parameter.
+    this._provider.app.use(async (ctx, next) => {
+      const {request: {method, path: p, query}} = ctx;
+      if (!p.startsWith('/interaction/') || method !== 'GET') return await next();
+      const details = await this._provider.interactionDetails(ctx.req, ctx.res);
+      if (Object.entries(query).length === 0) {
+        ctx.response.body = `waiting for ${details.prompt.name}`;
+        ctx.response.status = 200;
+        return;
+      }
+      switch (details.prompt.name) {
+        case 'login':
+          return await this._provider.interactionFinished(ctx.req, ctx.res,
+              {login: {accountId: query.login, remember: false}});
+        case 'consent': {
+          const grant = details.grantId
+            ? await this._provider.Grant.find(details.grantId)
+            : new this._provider.Grant({
+              accountId: details.session.accountId,
+              clientId: details.params.client_id,
+            });
+          const {prompt: {details: d}} = details;
+          if (d.missingOIDCScope) grant.addOIDCScope(d.missingOIDCScope.join(' '));
+          if (d.missingOIDCClaims) grant.addOIDCClaims(d.missingOIDCClaims);
+          if (d.missingResourceScopes) {
+            for (const [r, s] of Object.entries(d.missingResourceScopes)) {
+              grant.addResourceScope(r, s.join(' '));
+            }
+          }
+          const grantId = await grant.save();
+          return await this._provider.interactionFinished(ctx.req, ctx.res,
+              {consent: details.grantId ? {} : {grantId}});
+        }
+      }
+      return await next();
+    });
+  }
+
+  async stop() {
+    if (this._server == null) return;
+    await httpsClose.call(this._server);
+    this._server = null;
+  }
+}
+
+describe(__filename, function () {
+  let provider;
+  let pems; // {key, cert, certPath} from generateSelfSignedCert()
+  const backup = {};
+  const client = {client_id: 'the_client_id', client_secret: 'the_client_secret'};
+
+  before(async function () {
+    await common.init();
+    backup.settings = {
+      requireAuthentication: settings.requireAuthentication,
+      requireAuthorization: settings.requireAuthorization,
+      users: settings.users,
+    };
+    // Self-signed cert valid for localhost. The same PEM is used as both
+    // the server cert AND the CA bundle the plugin trusts.
+    pems = generateSelfSignedCert();
+
+    provider = new HttpsOidcProvider();
+    await provider.start({
+      tls: {key: pems.key, cert: pems.cert},
+      clients: [{
+        ...client,
+        redirect_uris: [new URL('/ep_openid_connect/callback', common.baseUrl).href],
+      }],
+    });
+  });
+
+  beforeEach(function () {
+    settings.requireAuthentication = true;
+    settings.requireAuthorization = false;
+    settings.users = {};
+  });
+
+  afterEach(function () {
+    settings.requireAuthentication = backup.settings.requireAuthentication;
+    settings.requireAuthorization = backup.settings.requireAuthorization;
+    settings.users = backup.settings.users;
+  });
+
+  after(async function () {
+    if (provider != null) await provider.stop();
+    provider = null;
+    if (pems && pems.dir) try { fs.rmSync(pems.dir, {recursive: true, force: true}); } catch (_) { /* ignore */ }
+  });
+
+  describe('loadCaBundle', function () {
+    const {loadCaBundle} = epOpenidConnect.exportedForTestingOnly;
+
+    it('returns null for an empty / missing value', function () {
+      assert.equal(loadCaBundle(undefined), null);
+      assert.equal(loadCaBundle(null), null);
+      assert.equal(loadCaBundle(''), null);
+    });
+
+    it('returns inline PEM content unchanged', function () {
+      assert.equal(loadCaBundle(pems.cert), pems.cert);
+    });
+
+    it('reads PEM content from a path', function () {
+      assert.equal(loadCaBundle(pems.certPath), pems.cert);
+    });
+
+    it('throws on a non-existent path', function () {
+      assert.throws(() => loadCaBundle('/this/path/does/not/exist.pem'),
+          /ENOENT|no such file/);
+    });
+  });
+
+  describe('discovery against a self-signed HTTPS provider', function () {
+    const baseSettings = () => ({
+      ...client,
+      base_url: common.baseUrl,
+      issuer: provider.issuer,
+      scope: ['openid', 'etherpad'],
+    });
+
+    it('fails without the ca setting', async function () {
+      // Discovery has to hit https://localhost:PORT/.well-known/... and
+      // there's no CA on the system trust store that signed our cert. The
+      // outer error from openid-client is the generic `TypeError: fetch
+      // failed`; the underlying TLS reason lives in err.cause.
+      await assert.rejects(
+          epOpenidConnect.loadSettings('loadSettings', {settings: {ep_openid_connect: {
+            ...baseSettings(),
+          }}}),
+          (err) => {
+            const messages = [];
+            for (let e = err; e != null; e = e.cause) {
+              if (e.message) messages.push(String(e.message));
+              if (e.code) messages.push(String(e.code));
+            }
+            const joined = messages.join(' | ');
+            return /self-signed|self signed|unable to verify|UNABLE_TO_VERIFY_LEAF_SIGNATURE|CERT|TLS/i.test(joined);
+          });
+    });
+
+    it('succeeds when ca points to a file', async function () {
+      await epOpenidConnect.loadSettings('loadSettings', {settings: {ep_openid_connect: {
+        ...baseSettings(),
+        ca: pems.certPath,
+      }}});
+      // No throw means discovery completed against the self-signed IdP.
+    });
+
+    it('succeeds when ca contains inline PEM content', async function () {
+      await epOpenidConnect.loadSettings('loadSettings', {settings: {ep_openid_connect: {
+        ...baseSettings(),
+        ca: pems.cert,
+      }}});
+    });
+  });
+});