ep_openid_connect 3.0.28 → 3.0.30

package/.github/workflows/automerge.yml

@@ -0,0 +1,30 @@
+name: Dependabot Automerge
+permissions:
+  contents: write
+  pull-requests: write
+on:
+  workflow_run:
+    workflows:
+      - Node.js Package
+    types:
+      - completed
+
+jobs:
+  automerge:
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.actor.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Automerge
+        uses: "pascalgn/automerge-action@v0.16.4"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          MERGE_METHOD: squash
+          MERGE_LABELS: ""
+          MERGE_RETRY_SLEEP: "100000"
+

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`
@@ -111,6 +119,13 @@ describes how the property's value is obtained:
   * If the descriptor object has a `claim` property that names an existing
     OpenID Connect claim, the value is set to the value of the claim. (If there
     is no such claim, `claim` has no effect.)
+  * If the descriptor object has a `role` property and the userinfo's `roles`
+    claim is an array containing that role string, the value is set to boolean
+    `true`. Useful for identity providers such as Azure/Entra ID and Keycloak
+    that publish role assignments through a single `roles` array claim rather
+    than a dedicated claim per property. Has no effect if the `roles` claim is
+    missing or doesn't include the named role. The `claim` rule is evaluated
+    first when both are present.
   * If the descriptor object has a `default` property and the account object
     property would otherwise be unset, the property is set to the given value.
     (Note that a property set to `undefined` is not the same as unset.)
@@ -198,6 +213,20 @@ provides suitable claims:
   },
 ```
 
+For identity providers that surface role assignments through a `roles` array
+claim instead (Azure/Entra ID, Keycloak, …), use `role`:
+
+```json
+  "ep_openid_connect": {
+    "scope": ["openid", "profile", "roles"],
+    "user_properties": {
+      "is_admin": {"role": "etherpad_admin"},
+      "readOnly": {"role": "etherpad_readonly", "default": false},
+      "canCreate": {"role": "etherpad_writer", "default": true}
+    }
+  },
+```
+
 To avoid breaking assumptions made by Etherpad, the `username` property cannot
 be altered via the `user_properties` setting.
 

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'}},
@@ -37,6 +47,11 @@ const validSettings = new Ajv().compile({
     user_properties: {values: {
       optionalProperties: {
         claim: {type: 'string'},
+        // `role` looks the named string up inside the `roles` claim's array
+        // value. Used by IdPs like Azure/Entra that surface role assignments
+        // via a single `roles` array claim instead of a dedicated claim per
+        // property. Set the property to `true` when the role is present.
+        role: {type: 'string'},
         // `default` is assigned verbatim to `req.session.user[propName]`,
         // so any JSON value (boolean for is_admin/readOnly/canCreate,
         // number, string, …) is fine. Use the JTD empty form so we don't
@@ -77,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.
@@ -111,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.
@@ -123,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:
@@ -151,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;
@@ -172,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;
 };
 
@@ -311,6 +361,11 @@ exports.authenticate = (hookName, {req, res, users}) => {
       delete req.session.user[propName];
     } else if (descriptor.claim != null && descriptor.claim in userinfo) {
       req.session.user[propName] = userinfo[descriptor.claim];
+    } else if (descriptor.role != null && Array.isArray(userinfo.roles) &&
+               userinfo.roles.includes(descriptor.role)) {
+      // Boolean `true` (not the string `"true"`) so that the value works
+      // directly with Etherpad's is_admin/readOnly/canCreate checks.
+      req.session.user[propName] = true;
     } else if ('default' in descriptor && !(propName in req.session.user)) {
       req.session.user[propName] = descriptor.default;
     }
@@ -368,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.28",
+  "version": "3.0.30",
   "description": "Etherpad plugin to authenticate users against an OpenID Connect provider.",
   "main": "index.js",
   "repository": {
@@ -24,7 +24,8 @@
   "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",

package/static/tests/backend/oidc-provider.js

@@ -31,6 +31,12 @@ class OidcProvider {
           'etherpad_canCreate',
           'name',
           'prop',
+          // `roles` is an array claim — Azure/Entra and Keycloak surface
+          // role assignments this way. The test account synthesises a
+          // `roles` array when the sub contains "role" (see findAccount
+          // below) so we can drive user_properties.X.role tests without
+          // disturbing the other test users' claim shape.
+          'roles',
         ],
       },
       cookies: {
@@ -49,6 +55,13 @@ class OidcProvider {
           etherpad_canCreate:
               sub.includes('admin') || (!sub.includes('readOnly') && !sub.includes('noCreate')),
           ...(sub === 'claimNull' ? {prop: null} : sub === 'claimVal' ? {prop: 'claimValue'} : {}),
+          // Synthesise a `roles` claim only for usernames that explicitly opt
+          // in via the "role" substring, so the other user_properties tests
+          // are unaffected. `emptyRoles` gets an empty array to exercise the
+          // "no matching role" path.
+          ...(sub.includes('emptyRoles') ? {roles: []}
+              : sub.includes('role') ? {roles: ['etherpad_admin', 'unrelated_role']}
+              : {}),
         }),
       }),
       jwks: {

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,
+      }}});
+    });
+  });
+});

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

@@ -0,0 +1,153 @@
+'use strict';
+
+// Coverage for `user_properties.<name>.role`: when the named role string is
+// present in the userinfo's `roles` array, the property is set to boolean
+// `true`. Useful for IdPs (Azure/Entra ID, Keycloak) that publish role
+// assignments through a single `roles` array claim rather than a dedicated
+// claim per property.
+
+const OidcProvider = require('../oidc-provider');
+const assert = require('assert').strict;
+const common = require('ep_etherpad-lite/tests/backend/common');
+const epOpenidConnect = require('../../../../index');
+const login = require('../login');
+const plugins = require('ep_etherpad-lite/static/js/pluginfw/plugin_defs');
+const settings = require('ep_etherpad-lite/node/utils/Settings');
+const supertest = require('supertest');
+
+describe(__filename, function () {
+  let agent;
+  const backup = {};
+  let provider;
+  let issuer;
+  const client = {
+    client_id: 'the_client_id',
+    client_secret: 'the_client_secret',
+  };
+  const basePluginSettings = {
+    ...client,
+    scope: ['openid', 'etherpad'],
+  };
+  let socket;
+
+  before(async function () {
+    await common.init();
+    if (!plugins.hooks.clientVars) plugins.hooks.clientVars = [];
+    backup.hooks = {clientVars: plugins.hooks.clientVars};
+    backup.settings = {
+      requireAuthentication: settings.requireAuthentication,
+      requireAuthorization: settings.requireAuthorization,
+      users: settings.users,
+    };
+    provider = new OidcProvider();
+    const clients =
+        [{...client, redirect_uris: [new URL('/ep_openid_connect/callback', common.baseUrl).href]}];
+    await provider.start({clients});
+  });
+
+  beforeEach(async function () {
+    agent = supertest.agent('');
+    issuer = provider.issuer;
+    settings.requireAuthentication = true;
+    settings.requireAuthorization = false;
+    settings.users = {};
+  });
+
+  afterEach(async function () {
+    if (socket != null) socket.close();
+    socket = null;
+    Object.assign(plugins.hooks, backup.hooks);
+    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;
+  });
+
+  const loadWithUserProperties = async (user_properties) => {
+    await epOpenidConnect.loadSettings('loadSettings', {settings: {ep_openid_connect: {
+      ...basePluginSettings,
+      base_url: common.baseUrl,
+      issuer,
+      user_properties,
+    }}});
+  };
+
+  // Login that captures the post-handshake session.user and returns it.
+  const loginAndGetUser = async (username) => {
+    const padId = common.randomString();
+    const url = new URL(`/p/${padId}`, common.baseUrl).toString();
+    const res = await login(agent, issuer, url, username);
+    assert.equal(res.request.url, url);
+    assert.equal(res.status, 200);
+    socket = await common.connect(res);
+    const userP = new Promise((resolve) => {
+      plugins.hooks.clientVars =
+          [{hook_fn: (hn, ctx) => resolve(ctx.socket.client.request.session.user)}];
+    });
+    const msg = await common.handshake(socket, padId);
+    assert.equal(msg.type, 'CLIENT_VARS', `not a CLIENT_VARS message: ${JSON.stringify(msg)}`);
+    return userP;
+  };
+
+  it('sets the property to boolean true when the role is present', async function () {
+    await loadWithUserProperties({is_admin: {role: 'etherpad_admin'}});
+    const user = await loginAndGetUser('roleAdmin');
+    assert.equal(user.is_admin, true, 'is_admin must be the boolean true, not a string');
+  });
+
+  it('leaves the property unset when the role is not in the roles array', async function () {
+    await loadWithUserProperties({is_admin: {role: 'missing_role'}});
+    const user = await loginAndGetUser('roleAdmin'); // has roles, just not this one
+    assert(!('is_admin' in user),
+        `is_admin should not be set when role is absent; got ${JSON.stringify(user.is_admin)}`);
+  });
+
+  it('leaves the property unset when roles array is empty', async function () {
+    await loadWithUserProperties({is_admin: {role: 'etherpad_admin'}});
+    const user = await loginAndGetUser('emptyRolesUser');
+    assert(!('is_admin' in user));
+  });
+
+  it('does not crash when the roles claim is entirely missing', async function () {
+    // `normalUser` doesn't have "role" in its sub, so the test account
+    // synthesises no `roles` claim at all. Pre-#111 code would have thrown
+    // `Cannot read properties of undefined (reading 'indexOf')`.
+    await loadWithUserProperties({is_admin: {role: 'etherpad_admin'}});
+    const user = await loginAndGetUser('normalUser');
+    assert(!('is_admin' in user));
+  });
+
+  it('falls through to default when role is absent', async function () {
+    await loadWithUserProperties({
+      is_admin: {role: 'missing_role', default: false},
+    });
+    const user = await loginAndGetUser('roleAdmin');
+    assert.equal(user.is_admin, false);
+  });
+
+  it('uses claim value in preference to role match', async function () {
+    // Both `claim` and `role` set: the explicit claim wins. The test account
+    // for `adminroleUser` emits `etherpad_is_admin: true` (sub contains
+    // "admin") AND `roles: ['etherpad_admin', ...]`. With a `claim`
+    // descriptor the role branch must not overwrite the claim's value.
+    await loadWithUserProperties({
+      is_admin: {claim: 'etherpad_is_admin', role: 'should_not_match'},
+    });
+    const user = await loginAndGetUser('adminroleUser');
+    assert.equal(user.is_admin, true); // came from claim, not role fallback
+  });
+
+  it('role can grant a property whose claim is absent', async function () {
+    // `claim` is checked first but only fires when the claim key is *in*
+    // userinfo. If it isn't, the role branch should run.
+    await loadWithUserProperties({
+      is_admin: {claim: 'definitely_not_a_claim', role: 'etherpad_admin'},
+    });
+    const user = await loginAndGetUser('roleUser');
+    assert.equal(user.is_admin, true);
+  });
+});