ep_openid_connect 3.0.27 → 3.0.29

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/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+#### Behaviour changes
+
+  * `token_endpoint_auth_method` now defaults to auto-detection from the
+    identity provider's discovery document. The plugin prefers
+    `client_secret_post` when advertised and falls back to
+    `client_secret_basic`. This fixes silent token-endpoint
+    `WWWAuthenticateChallengeError` failures on GitLab.com (which advertises
+    both methods but rejects `client_secret_basic`). Users who previously
+    relied on the `client_secret_basic` default without setting it explicitly
+    may now exchange tokens via `client_secret_post`; set the option
+    explicitly to pin a specific method.
+
 ## v3.0.0
 
 Released 2022-03-04.

package/README.md

@@ -49,11 +49,14 @@ Etherpad's `requireAuthentication` setting must be `true`.
 * `client_id` (required): The OAuth2 client ID issued by the identity provider.
 * `client_secret` (required): The OAuth2 client secret issued by the identity
   provider.
-* `token_endpoint_auth_method` (optional; defaults to `client_secret_basic`):
-  Client authentication method to use for token endpoint requests. Supported
-  values are `client_secret_basic` and `client_secret_post`. Use
-  `client_secret_post` if your identity provider expects the client secret in
-  the token request body instead of the HTTP `Authorization` header.
+* `token_endpoint_auth_method` (optional; auto-detected by default): Client
+  authentication method to use for token endpoint requests. Supported values
+  are `client_secret_basic` and `client_secret_post`. When not set, the plugin
+  inspects the identity provider's discovery document
+  (`token_endpoint_auth_methods_supported`) and picks `client_secret_post` if
+  the provider advertises it, otherwise `client_secret_basic`. Set this
+  explicitly to force a specific method — for example, if your identity
+  provider advertises both but your client is registered for only one.
 * `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`.
@@ -108,6 +111,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.)
@@ -195,6 +205,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

@@ -10,7 +10,6 @@ for (const level of ['debug', 'info', 'warn', 'error']) {
 const defaultSettings = {
   prohibited_usernames: ['admin', 'guest'],
   scope: ['openid'],
-  token_endpoint_auth_method: 'client_secret_basic',
   user_properties: {},
 };
 let settings;
@@ -38,6 +37,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
@@ -78,7 +82,41 @@ const isHttp = (urlString) => {
   }
 };
 
-const discoverConfig = async (issuerUrl, clientId, clientAuth) => {
+// 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.
+//
+// Preference order when no override is set:
+//   1. `client_secret_post` if the IdP advertises it (matches openid-client@6's
+//      own default and works with every public IdP we've tested — notably
+//      GitLab.com, which rejects `client_secret_basic` at the token endpoint
+//      even though it lists it in discovery).
+//   2. `client_secret_basic` if the IdP advertises only that.
+//   3. `client_secret_basic` if the IdP advertises nothing we recognise (RFC
+//      8414 §2 says the absence of the field defaults to `client_secret_basic`).
+const pickAuthMethod = (supported, override) => {
+  if (override) return override;
+  if (Array.isArray(supported)) {
+    if (supported.includes('client_secret_post')) return 'client_secret_post';
+    if (supported.includes('client_secret_basic')) return 'client_secret_basic';
+  }
+  return 'client_secret_basic';
+};
+
+const clientAuthFor = (method, secret) => {
+  switch (method) {
+    case 'client_secret_basic':
+      // eslint-disable-next-line new-cap
+      return oidc.ClientSecretBasic(secret);
+    case 'client_secret_post':
+      // eslint-disable-next-line new-cap
+      return oidc.ClientSecretPost(secret);
+    default:
+      throw new Error(`Unsupported token endpoint auth method: ${method}`);
+  }
+};
+
+const fetchServerMetadata = async (issuerUrl, clientId) => {
   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.
@@ -94,7 +132,13 @@ const discoverConfig = async (issuerUrl, clientId, clientAuth) => {
     ? {execute: [oidc.allowInsecureRequests]}
     : undefined;
   try {
-    return await oidc.discovery(url, clientId, undefined, clientAuth, options);
+    // 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);
+    return tempConfig.serverMetadata();
   } catch (err) {
     // The URL used to get the issuer metadata doesn't exactly follow RFC 8615; see:
     // https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig
@@ -111,36 +155,30 @@ const discoverConfig = async (issuerUrl, clientId, clientAuth) => {
   }
 };
 
-const getClientAuth = (settings) => {
-  switch (settings.token_endpoint_auth_method) {
-    case 'client_secret_basic':
-      // eslint-disable-next-line new-cap
-      return oidc.ClientSecretBasic(settings.client_secret);
-    case 'client_secret_post':
-      // eslint-disable-next-line new-cap
-      return oidc.ClientSecretPost(settings.client_secret);
-    default:
-      throw new Error(
-          `Unsupported token endpoint auth method: ${settings.token_endpoint_auth_method}`);
-  }
-};
-
 const buildConfig = async (settings) => {
-  // openid-client@5 defaulted the token endpoint auth method to
-  // `client_secret_basic`; v6 defaults to `client_secret_post`. Pin the
-  // default method explicitly so existing IdP registrations keep working.
-  const clientAuth = getClientAuth(settings);
+  // 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) {
-    const config =
-        await discoverConfig(settings.issuer, settings.client_id, clientAuth);
-    logger.info('OpenID Connect Discovery complete.');
-    return config;
+    serverMetadata = await fetchServerMetadata(settings.issuer, settings.client_id);
+    phaseLog = 'OpenID Connect Discovery complete.';
+  } else {
+    serverMetadata = settings.issuer_metadata;
+    phaseLog = 'Configured from issuer_metadata.';
   }
-  const config =
-      new oidc.Configuration(settings.issuer_metadata, settings.client_id, undefined, clientAuth);
-  if (isHttp(settings.issuer_metadata && settings.issuer_metadata.issuer)) {
+  const method = pickAuthMethod(
+      serverMetadata && serverMetadata.token_endpoint_auth_methods_supported,
+      settings.token_endpoint_auth_method);
+  const clientAuth = clientAuthFor(method, settings.client_secret);
+  const config = new oidc.Configuration(
+      serverMetadata, settings.client_id, undefined, clientAuth);
+  if (isHttp(serverMetadata && serverMetadata.issuer)) {
     oidc.allowInsecureRequests(config);
   }
+  const source = settings.token_endpoint_auth_method ? 'configured' : 'auto-picked';
+  logger.info(`${phaseLog} Token endpoint auth method: ${method} (${source}).`);
   return config;
 };
 
@@ -179,7 +217,6 @@ exports.loadSettings = async (hookName, {settings: {ep_openid_connect: s = {}}})
   if (!settings.base_url.endsWith('/')) settings.base_url += '/';
   logger.debug('Settings:', {...settings, client_secret: '********'});
   oidcConfig = await buildConfig(settings);
-  logger.info('Configured.');
 };
 
 exports.expressCreateServer = (hookName, {app}) => {
@@ -279,6 +316,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;
     }
@@ -336,5 +378,6 @@ exports.preAuthorize = (hookName, {req}) => {
 exports.exportedForTestingOnly = {
   callbackUrlFromRequest,
   defaultSettings,
+  pickAuthMethod,
   validSettings,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ep_openid_connect",
-  "version": "3.0.27",
+  "version": "3.0.29",
   "description": "Etherpad plugin to authenticate users against an OpenID Connect provider.",
   "main": "index.js",
   "repository": {

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/auto_pick_auth_method.js

@@ -0,0 +1,117 @@
+'use strict';
+
+// End-to-end coverage for the token_endpoint_auth_method auto-pick: spin up a
+// dedicated OIDC provider whose discovery doc advertises only one auth method,
+// load the plugin without an explicit override, and confirm a real login flow
+// succeeds — i.e. the plugin chose the advertised method.
+
+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;
+  let provider;
+  const backup = {};
+  const client = {
+    client_id: 'the_client_id',
+    client_secret: 'the_client_secret',
+  };
+  const basePluginSettings = {
+    ...client,
+    scope: ['openid', 'etherpad'],
+    user_properties: {
+      is_admin: {claim: 'etherpad_is_admin'},
+      readOnly: {claim: 'etherpad_readOnly'},
+      canCreate: {claim: 'etherpad_canCreate'},
+    },
+  };
+
+  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,
+    };
+  });
+
+  beforeEach(function () {
+    agent = supertest.agent('');
+    settings.requireAuthentication = true;
+    settings.requireAuthorization = false;
+    settings.users = {};
+  });
+
+  afterEach(async function () {
+    if (provider != null) await provider.stop();
+    provider = null;
+    Object.assign(plugins.hooks, backup.hooks);
+    settings.requireAuthentication = backup.settings.requireAuthentication;
+    settings.requireAuthorization = backup.settings.requireAuthorization;
+    settings.users = backup.settings.users;
+  });
+
+  // Restart `provider` with the given allowed auth methods, then load the
+  // plugin pointed at it with NO explicit token_endpoint_auth_method (so the
+  // picker runs).
+  const startProvider = async (allowedAuthMethods) => {
+    const redirectUri = new URL('/ep_openid_connect/callback', common.baseUrl).href;
+    provider = new OidcProvider();
+    await provider.start({
+      // oidc-provider v9: the global allow-list drives the advertised
+      // token_endpoint_auth_methods_supported and is enforced at the token
+      // endpoint. Each client must also declare which method it uses.
+      clientAuthMethods: allowedAuthMethods,
+      clients: [{
+        ...client,
+        redirect_uris: [redirectUri],
+        token_endpoint_auth_method: allowedAuthMethods[0],
+      }],
+    });
+    await epOpenidConnect.loadSettings('loadSettings', {settings: {ep_openid_connect: {
+      ...basePluginSettings,
+      base_url: common.baseUrl,
+      issuer: provider.issuer,
+      // Deliberately omit token_endpoint_auth_method — that's what we're testing.
+    }}});
+  };
+
+  it('picks client_secret_post when only that is advertised', async function () {
+    await startProvider(['client_secret_post']);
+    const url = new URL(`/p/${common.randomString()}`, common.baseUrl).toString();
+    const res = await login(agent, provider.issuer, url, 'normalUser');
+    assert.equal(res.request.url, url,
+        `expected redirect back to ${url}, got ${res.request.url}`);
+    assert.equal(res.status, 200);
+  });
+
+  it('picks client_secret_basic when only that is advertised', async function () {
+    await startProvider(['client_secret_basic']);
+    const url = new URL(`/p/${common.randomString()}`, common.baseUrl).toString();
+    const res = await login(agent, provider.issuer, url, 'normalUser');
+    assert.equal(res.request.url, url,
+        `expected redirect back to ${url}, got ${res.request.url}`);
+    assert.equal(res.status, 200);
+  });
+
+  it('prefers client_secret_post when both are advertised', async function () {
+    // When both methods are on offer the plugin must pick _post (matches the
+    // openid-client@6 default and is the one GitLab.com actually accepts at
+    // the token endpoint). The test client is registered as _post-only, so a
+    // _basic attempt would 401 at the token endpoint.
+    await startProvider(['client_secret_post', 'client_secret_basic']);
+    const url = new URL(`/p/${common.randomString()}`, common.baseUrl).toString();
+    const res = await login(agent, provider.issuer, url, 'normalUser');
+    assert.equal(res.request.url, url,
+        `expected redirect back to ${url}, got ${res.request.url}`);
+    assert.equal(res.status, 200);
+  });
+});

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

@@ -0,0 +1,71 @@
+'use strict';
+
+const assert = require('assert').strict;
+const {pickAuthMethod} = require('../../../..').exportedForTestingOnly;
+
+describe(__filename, function () {
+  describe('with no override', function () {
+    it('prefers client_secret_post when advertised', function () {
+      assert.equal(
+          pickAuthMethod(['client_secret_basic', 'client_secret_post']),
+          'client_secret_post');
+    });
+
+    it('uses client_secret_basic when only that is advertised', function () {
+      assert.equal(pickAuthMethod(['client_secret_basic']), 'client_secret_basic');
+    });
+
+    it('uses client_secret_post when only that is advertised', function () {
+      assert.equal(pickAuthMethod(['client_secret_post']), 'client_secret_post');
+    });
+
+    it('ignores unsupported methods', function () {
+      // None of these are methods this plugin can implement, so the picker
+      // must fall back rather than pretend to support them.
+      assert.equal(
+          pickAuthMethod(['private_key_jwt', 'client_secret_jwt', 'none']),
+          'client_secret_basic');
+    });
+
+    it('prefers client_secret_post even when other methods are advertised first', function () {
+      assert.equal(
+          pickAuthMethod(['private_key_jwt', 'client_secret_post', 'client_secret_basic']),
+          'client_secret_post');
+    });
+
+    it('falls back to client_secret_basic when supported is undefined', function () {
+      // RFC 8414 §2: absence of token_endpoint_auth_methods_supported defaults
+      // to client_secret_basic.
+      assert.equal(pickAuthMethod(undefined), 'client_secret_basic');
+    });
+
+    it('falls back to client_secret_basic when supported is empty', function () {
+      assert.equal(pickAuthMethod([]), 'client_secret_basic');
+    });
+
+    it('falls back to client_secret_basic when supported is not an array', function () {
+      assert.equal(pickAuthMethod('client_secret_post'), 'client_secret_basic');
+      assert.equal(pickAuthMethod(null), 'client_secret_basic');
+    });
+  });
+
+  describe('with override', function () {
+    it('honours an explicit client_secret_basic override', function () {
+      assert.equal(
+          pickAuthMethod(['client_secret_post'], 'client_secret_basic'),
+          'client_secret_basic');
+    });
+
+    it('honours an explicit client_secret_post override', function () {
+      assert.equal(
+          pickAuthMethod(['client_secret_basic'], 'client_secret_post'),
+          'client_secret_post');
+    });
+
+    it('honours override even when supported list is missing', function () {
+      assert.equal(
+          pickAuthMethod(undefined, 'client_secret_post'),
+          'client_secret_post');
+    });
+  });
+});

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