ep_openid_connect 3.0.28 → 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/README.md

@@ -111,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.)
@@ -198,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

@@ -37,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
@@ -311,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;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ep_openid_connect",
-  "version": "3.0.28",
+  "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/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);
+  });
+});