ep_openid_connect 2.0.7 → 2.1.2

package/.github/workflows/backend-tests.yml

@@ -1,6 +1,3 @@
-# You need to change lines 38 and 46 in case the plugin's name on npmjs.com is different
-# from the repository name
-
 name: "Backend tests"
 
 # any branch is useful for testing before a PR is submitted
@@ -17,6 +14,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+    - uses: actions/setup-node@v2
+      with:
+        node-version: 12
+
     - name: Install libreoffice
       run: |
         sudo add-apt-repository -y ppa:libreoffice/ppa
@@ -32,19 +33,29 @@ jobs:
     - name: Install all dependencies and symlink for ep_etherpad-lite
       run: src/bin/installDeps.sh
 
-    # clone this repository into node_modules/ep_plugin-name
     - name: Checkout plugin repository
       uses: actions/checkout@v2
       with:
-        path: ./node_modules/${{github.event.repository.name}}
+        path: ./node_modules/__tmp
+
+    - name: Determine plugin name
+      id: plugin_name
+      run: |
+        cd ./node_modules/__tmp
+        npx -c 'printf %s\\n "::set-output name=plugin_name::${npm_package_name}"'
+
+    - name: Rename plugin directory
+      run: |
+        mv ./node_modules/__tmp ./node_modules/"${PLUGIN_NAME}"
+      env:
+        PLUGIN_NAME: ${{ steps.plugin_name.outputs.plugin_name }}
 
     - name: Install plugin dependencies
       run: |
-        cd node_modules/${{github.event.repository.name}}
+        cd ./node_modules/"${PLUGIN_NAME}"
         npm ci
+      env:
+        PLUGIN_NAME: ${{ steps.plugin_name.outputs.plugin_name }}
 
     - name: Run the backend tests
       run: cd src && npm test
-
-##ETHERPAD_NPM_V=2
-## NPM configuration automatically created using src/bin/plugins/updateAllPluginsScript.sh

package/.github/workflows/frontend-tests.yml

@@ -0,0 +1,92 @@
+# Publicly credit Sauce Labs because they generously support open source
+# projects.
+name: "frontend tests powered by Sauce Labs"
+
+on: [push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Generate Sauce Labs strings
+      id: sauce_strings
+      run: |
+        printf %s\\n '::set-output name=name::${{github.event.repository.name}} ${{ github.workflow }} - ${{ github.job }}'
+        printf %s\\n '::set-output name=tunnel_id::${{ github.run_id }}-${{ github.run_number }}-${{ github.job }}'
+
+    - uses: actions/setup-node@v2
+      with:
+        node-version: 12
+
+    - name: Check out Etherpad core
+      uses: actions/checkout@v2
+      with:
+        repository: ether/etherpad-lite
+
+    - name: Check out the plugin
+      uses: actions/checkout@v2
+      with:
+        path: ./node_modules/__tmp
+
+    - name: export GIT_HASH to env
+      id: environment
+      run: |
+        cd ./node_modules/__tmp
+        echo "::set-output name=sha_short::$(git rev-parse --short ${{ github.sha }})"
+
+    - name: Determine plugin name
+      id: plugin_name
+      run: |
+        cd ./node_modules/__tmp
+        npx -c 'printf %s\\n "::set-output name=plugin_name::${npm_package_name}"'
+
+    - name: Rename plugin directory
+      env:
+        PLUGIN_NAME: ${{ steps.plugin_name.outputs.plugin_name }}
+      run: |
+        mv ./node_modules/__tmp ./node_modules/"${PLUGIN_NAME}"
+
+    - name: Install plugin dependencies
+      env:
+        PLUGIN_NAME: ${{ steps.plugin_name.outputs.plugin_name }}
+      run: |
+        cd ./node_modules/"${PLUGIN_NAME}"
+        npm ci
+
+    # This must be run after setting up the plugin, otherwise npm will try to
+    # hoist common dependencies by removing them from src/node_modules and
+    # installing them in the top-level node_modules. As of v6.14.10, npm's hoist
+    # logic appears to be buggy, because it sometimes removes dependencies from
+    # src/node_modules but fails to add them to the top-level node_modules. Even
+    # if npm correctly hoists the dependencies, the hoisting seems to confuse
+    # tools such as `npm outdated`, `npm update`, and some ESLint rules.
+    - name: Install Etherpad core dependencies
+      run: src/bin/installDeps.sh
+
+    - name: Create settings.json
+      run: cp settings.json.template settings.json
+
+    - name: Disable import/export rate limiting
+      run: |
+        sed -e '/^ *"importExportRateLimiting":/,/^ *\}/ s/"max":.*/"max": 0/' -i settings.json
+
+    - name: Remove standard frontend test files
+      run: rm -rf src/tests/frontend/specs
+
+    - uses: saucelabs/sauce-connect-action@v1
+      with:
+        username: ${{ secrets.SAUCE_USERNAME }}
+        accessKey: ${{ secrets.SAUCE_ACCESS_KEY }}
+        tunnelIdentifier: ${{ steps.sauce_strings.outputs.tunnel_id }}
+
+    - name: Run the frontend tests
+      shell: bash
+      env:
+        SAUCE_USERNAME: ${{ secrets.SAUCE_USERNAME }}
+        SAUCE_ACCESS_KEY: ${{ secrets.SAUCE_ACCESS_KEY }}
+        SAUCE_NAME: ${{ steps.sauce_strings.outputs.name }}
+        TRAVIS_JOB_NUMBER: ${{ steps.sauce_strings.outputs.tunnel_id }}
+        GIT_HASH: ${{ steps.environment.outputs.sha_short }}
+      run: |
+        src/tests/frontend/travis/runner.sh

package/.github/workflows/npmpublish.yml

@@ -56,15 +56,22 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v1
         with:
           node-version: 12
           registry-url: https://registry.npmjs.org/
-      - run: git config user.name 'github-actions[bot]'
-      - run: git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
-      - run: npm ci
-      - run: npm version patch
-      - run: git push --follow-tags
+      - name: Bump version (patch)
+        run: |
+          LATEST_TAG=$(git describe --tags --abbrev=0) || exit 1
+          NEW_COMMITS=$(git rev-list --count "${LATEST_TAG}"..) || exit 1
+          [ "${NEW_COMMITS}" -gt 0 ] || exit 0
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          npm ci
+          npm version patch
+          git push --follow-tags
       # `npm publish` must come after `git push` otherwise there is a race
       # condition: If two PRs are merged back-to-back then master/main will be
       # updated with the commits from the second PR before the first PR's
@@ -78,6 +85,3 @@ jobs:
       - run: npm publish
         env:
           NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
-
-##ETHERPAD_NPM_V=2
-## NPM configuration automatically created using bin/plugins/updateAllPluginsScript.sh

package/README.md

@@ -34,18 +34,30 @@ Etherpad's `requireAuthentication` setting must be `true`.
 
 ### Configuration Details
 
-* `issuer` (required): The base URL of the OpenID Connect identity provider,
-  used to perform discovery of the endpoints.
+* `issuer` (required if `issuer_metadata` is not set): The base URL of the
+  OpenID Connect identity provider, used to discover the relevant OpenID Connect
+  endpoints. If set, your identity provider must support the [OpenID Connect
+  Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)
+  protocol.
+* `issuer_metadata` (required if `issuer` is not set): Object containing details
+  about your OpenID Connect identity provider. Used for manual configuration if
+  your identity provider does not support the Discovery protocol. If your
+  identity provider does support Discovery, you are encouraged to set `issuer`
+  instead. For properties, see the [documentation for the openid-client `Issuer`
+  object
+  constructor](https://github.com/panva/node-openid-client/blob/v4.7.4/docs/README.md#new-issuermetadata).
 * `client_id` (required): The OAuth2 client ID issued by the identity provider.
 * `client_secret` (required): The OAuth2 client secret issued by the identity
   provider.
 * `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`.
-* `displayname_claim` (optional; defaults to `"name"`): The claim containing the
-  name to display in the pad's user list.
+* `displayname_claim` (optional; defaults to `"name"`): The default value of
+  `user_properties.displayname.claim`. **Deprecated:** Set
+  `user_properties.displayname.claim` instead.
 * `response_types` (optional; defaults to `["code"]`): List of OpenID Connect
   response types.
+* `scope` (optional; defaults to `["openid"]`): List of OAuth2 scope strings.
 * `permit_displayname_change` (optional; defaults to `false`): Whether users may
   change their displayed name.
 * `prohibited_usernames` (optional; defaults to `['admin', 'guest']`): List of
@@ -54,6 +66,9 @@ Etherpad's `requireAuthentication` setting must be `true`.
   the users in the `users` setting and to avoid conflicts with other plugins
   (such as
   [ep\_readonly\_guest](https://github.com/ether/ep_readonly_guest#readme)).
+* `user_properties` (optional): Object that controls the automatic creation of
+  additional properties on each authenticated user's account object. See below
+  for details.
 
 ## Interaction with the `users` Setting
 
@@ -63,15 +78,18 @@ identifier for the user.) Many identity providers (such as GitLab) identify
 users by a numeric user ID, so the `sub` claim (and thus the Etherpad username)
 will probably look something like "5374".
 
-All values associated with that username in the `settings.json` `users` object
-are applied to the user, including `is_admin`, `readOnly`, and `canCreate`.
-
-For example, if you want the user identified by "5374" to be a read-only user,
-you would add the following to your `settings.json`:
+Each authenticated user gets their own account object. Default properties for a
+user's account object come from the `users` setting in `settings.json`. Etherpad
+uses the `is_admin`, `readOnly`, and `canCreate` properties to control access,
+and this plugin uses the `displayname` property for the name displayed in the
+user list. For example, the following sets the default display name to
+"Firstname Lastname" and the default access to read-only for the user identified
+by "5374":
 
 ```json
   "users": {
     "5374": {
+      "displayname": "Firstname Lastname",
       "readOnly": true
     }
   },
@@ -82,6 +100,54 @@ you can use the `prohibited_usernames` settings to force an authentication error
 if the `sub` claim happens to match. This is useful for preventing a malicious
 identity provider from gaining admin access to your Etherpad instance.
 
+The `user_properties` setting can be used to automatically add or change
+properties on a user's account object when the user authenticates. The
+`user_properties` setting maps a property name to an object that describes how
+the property's value is obtained. For example:
+
+```json
+  "ep_openid_connect": {
+    "user_properties": {
+      "fromClaimWithDefault": {
+        "claim": "claimName",
+        "default": "default value"
+      },
+      "fromClaimOrUnset": {
+        "claim": "claimName"
+      },
+      "fixedValue": {
+        "default": "fixed value"
+      }
+    }
+  },
+```
+
+The above example sets properties as follows:
+* Each user's `fromClaimWithDefault` property is set to the value of the user's
+  `claimName` claim if present, otherwise the property is left unchanged if
+  already set, otherwise it is set to the string `"default value"`.
+* Each user's `fromClaimOrUnset` property is set to the value of the user's
+  `claimName` claim if present, otherwise the property is left unset/unchanged.
+* Each user's `fixedValue` property is set to the string `"fixed value"`
+  unless already set.
+
+You can use this feature to control access in the OpenID Connect provider if it
+provides suitable claims:
+
+```json
+  "ep_openid_connect": {
+    "scope": ["openid", "etherpad"],
+    "user_properties": {
+      "is_admin": {"claim": "etherpad_is_admin"},
+      "readOnly": {"claim": "etherpad_readOnly"},
+      "canCreate": {"claim": "etherpad_canCreate"}
+    }
+  },
+```
+
+To avoid breaking assumptions made by Etherpad, the `username` property cannot
+be altered via the `user_properties` setting.
+
 ## Interaction with the ep\_readonly\_guest Plugin
 
 The [ep\_readonly\_guest

package/index.js

@@ -5,78 +5,147 @@ const {URL} = require('url');
 const {Issuer, generators} = require('openid-client');
 const authorManager = require('ep_etherpad-lite/node/db/AuthorManager');
 
-const pluginName = 'ep_openid_connect';
-const logger = log4js.getLogger(pluginName);
+const logger = log4js.getLogger('ep_openid_connect');
 const settings = {
   displayname_claim: 'name',
   response_types: ['code'],
   permit_displayname_change: false,
   prohibited_usernames: ['admin', 'guest'],
+  scope: ['openid'],
+  user_properties: {},
 };
 let oidcClient = null;
 
-const ep = (endpoint) => `/${pluginName}/${endpoint}`;
+const ep = (endpoint) => `/ep_openid_connect/${endpoint}`;
 const endpointUrl = (endpoint) => new URL(ep(endpoint).substr(1), settings.base_url).toString();
 
-exports.loadSettings = async (hookName, {settings: {[pluginName]: config = {}}}) => {
+const validateSubClaim = (sub) => {
+  if (typeof sub !== 'string' || // 'sub' claim must exist as a string per OIDC spec.
+      sub === '' || // Empty string doesn't make sense.
+      sub === '__proto__' || // Prevent prototype pollution.
+      settings.prohibited_usernames.includes(sub)) {
+    throw new Error('invalid sub claim');
+  }
+};
+
+const discoverIssuer = async (issuerUrl) => {
+  issuerUrl = 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.
+  if (issuerUrl.search) {
+    throw new Error(`Unexpected query in issuer URL (${issuerUrl}): ${issuerUrl.search}`);
+  }
+  if (issuerUrl.hash) {
+    throw new Error(`Unexpected fragment in issuer URL (${issuerUrl}): ${issuerUrl.hash}`);
+  }
+  let issuer;
+  try {
+    issuer = await Issuer.discover(issuerUrl.href);
+  } 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
+    const discoveryUrl = new URL(issuerUrl);
+    if (!discoveryUrl.pathname.includes('/.well-known/')) {
+      discoveryUrl.pathname =
+          `${discoveryUrl.pathname.replace(/\/$/, '')}/.well-known/openid-configuration`;
+    }
+    logger.error(
+        'Failed to discover issuer metadata via OpenID Connect Discovery ' +
+        '(https://openid.net/specs/openid-connect-discovery-1_0.html). ' +
+        `Does your issuer support Discovery? (hint: ${discoveryUrl})`);
+    throw err;
+  }
+  logger.info('OpenID Connect Discovery complete.');
+  return issuer;
+};
+
+const getIssuer = async (settings) => {
+  if (settings.issuer) return await discoverIssuer(settings.issuer);
+  return new Issuer(settings.issuer_metadata);
+};
+
+exports.loadSettings = async (hookName, {settings: {ep_openid_connect: config = {}}}) => {
   Object.assign(settings, config);
-  for (const setting of ['base_url', 'client_id', 'client_secret', 'issuer']) {
+  for (const setting of ['base_url', 'client_id', 'client_secret']) {
     if (!settings[setting]) {
-      logger.error(`Required setting missing from settings.json: ${pluginName}.${setting}`);
+      logger.error(`Required setting missing from settings.json: ep_openid_connect.${setting}`);
       return;
     }
   }
+  if (!settings.issuer && !settings.issuer_metadata) {
+    logger.error(
+        'Either ep_openid_connect.issuer or ep_openid_connect.issuer_metadata must be set');
+    return;
+  }
+  if (settings.issuer && settings.issuer_metadata) {
+    logger.warn('Ignoring ep_openid_connect.issuer_metadata setting ' +
+                'because ep_openid_connect.issuer is set');
+  }
   // Make sure base_url ends with '/' so that relative URLs are appended:
   if (!settings.base_url.endsWith('/')) settings.base_url += '/';
-  oidcClient = new (await Issuer.discover(settings.issuer)).Client({
+  settings.user_properties = {
+    displayname: {claim: settings.displayname_claim},
+    ...settings.user_properties,
+    // The username property must always match the key used in settings.users.
+    username: {claim: 'sub'},
+  };
+  oidcClient = new (await getIssuer(settings)).Client({
     client_id: settings.client_id,
     client_secret: settings.client_secret,
     response_types: settings.response_types,
     redirect_uris: [endpointUrl('callback')],
   });
-  logger.info('Client discovery complete. Configured.');
+  logger.info('Configured.');
 };
 
 exports.clientVars = (hookName, context) => {
   if (oidcClient == null) return;
   const {permit_displayname_change} = settings;
-  return {[pluginName]: {permit_displayname_change}};
+  return {ep_openid_connect: {permit_displayname_change}};
 };
 
 exports.expressCreateServer = (hookName, {app}) => {
   if (oidcClient == null) return;
   logger.debug('Configuring auth routes');
-  app.get(ep('callback'), (req, res, next) => {
-    logger.debug(`Processing ${req.url}`);
-    (async () => {
+  app.get(ep('callback'), async (req, res, next) => {
+    // This handler MUST NOT redirect to a page that requires authentication if there is a problem,
+    // otherwise the user could be caught in an infinite redirect loop.
+    try {
+      logger.debug(`Processing ${req.url}`);
       const params = oidcClient.callbackParams(req);
-      const oidcSession = req.session[pluginName] || {};
-      const {authParams} = oidcSession;
-      if (authParams == null) throw new Error('no authentication paramters found in session state');
-      const tokenset = await oidcClient.callback(endpointUrl('callback'), params, authParams);
+      const oidcSession = req.session.ep_openid_connect || {};
+      if (oidcSession.authParams == null) throw new Error('missing authentication paramters');
+      const tokenset =
+          await oidcClient.callback(endpointUrl('callback'), params, oidcSession.authParams);
       const userinfo = await oidcClient.userinfo(tokenset);
-      if (settings.prohibited_usernames.indexOf(userinfo.sub) !== -1) {
-        throw new Error(`authenticated user's 'sub' claim (${userinfo.sub}) is not permitted`);
-      }
-      oidcSession.userinfo = userinfo;
+      validateSubClaim(userinfo.sub);
       // The user has successfully authenticated, but don't set req.session.user here -- do it in
       // the authenticate hook so that Etherpad can log the authentication success. However, DO "log
       // out" the previous user to force the authenticate hook to run in case the user was already
       // authenticated as someone else.
       delete req.session.user;
+      // userinfo should not be stored in req.session until after all checks have passed. (Otherwise
+      // it would be too easy to accidentally introduce a vulnerability.)
+      oidcSession.userinfo = userinfo;
       res.redirect(oidcSession.next || settings.base_url);
       // Defer deletion of state until success so that the user can reload the page to retry after a
       // transient backchannel failure.
       delete oidcSession.authParams;
       delete oidcSession.next;
-    })().catch(next);
+    } catch (err) {
+      return next(err);
+    }
   });
   app.get(ep('login'), (req, res, next) => {
     logger.debug(`Processing ${req.url}`);
-    if (req.session[pluginName] == null) req.session[pluginName] = {};
-    const oidcSession = req.session[pluginName];
+    if (req.session.ep_openid_connect == null) req.session.ep_openid_connect = {};
+    const oidcSession = req.session.ep_openid_connect;
     oidcSession.next = req.query.redirect_uri || settings.base_url;
-    oidcSession.authParams = {nonce: generators.nonce(), state: generators.state()};
+    oidcSession.authParams = {
+      nonce: generators.nonce(),
+      scope: settings.scope.join(' '),
+      state: generators.state(),
+    };
     res.redirect(oidcClient.authorizationUrl(oidcSession.authParams));
   });
   app.get(ep('logout'), (req, res) => req.session.destroy(() => res.redirect(settings.base_url)));
@@ -85,21 +154,26 @@ exports.expressCreateServer = (hookName, {app}) => {
 exports.authenticate = (hookName, {req, res, users}) => {
   if (oidcClient == null) return;
   logger.debug('authenticate hook for', req.url);
-  const {session} = req;
-  const {[pluginName]: {userinfo = {}} = {}} = session;
-  const {sub} = userinfo;
-  if (sub == null) {
+  const {ep_openid_connect: {userinfo} = {}} = req.session;
+  if (userinfo == null) { // Nullish means the user isn't authenticated.
     // Out of an abundance of caution, clear out the old state, nonce, and userinfo (if present) to
     // force regeneration.
-    delete session[pluginName];
+    delete req.session.ep_openid_connect;
     // Authn failed. Let another plugin try to authenticate the user.
     return;
   }
   // Successfully authenticated.
-  if (users[sub] == null) users[sub] = {};
-  session.user = users[sub];
-  session.user.username = sub;
-  session.user.displayname = userinfo[settings.displayname_claim] || session.user.displayname;
+  logger.info('Successfully authenticated user with userinfo:', userinfo);
+  req.session.user = users[userinfo.sub];
+  if (req.session.user == null) req.session.user = users[userinfo.sub] = {};
+  for (const [propName, descriptor] of Object.entries(settings.user_properties)) {
+    if (descriptor.claim != null && descriptor.claim in userinfo) {
+      req.session.user[propName] = userinfo[descriptor.claim];
+    } else if ('default' in descriptor && !(propName in req.session.user)) {
+      req.session.user[propName] = descriptor.default;
+    }
+  }
+  logger.debug('User properties:', req.session.user);
   return true;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ep_openid_connect",
-  "version": "2.0.7",
+  "version": "2.1.2",
   "description": "Etherpad plugin to authenticate users against an OpenID Connect provider.",
   "main": "index.js",
   "repository": {
@@ -23,18 +23,18 @@
   },
   "homepage": "https://github.com/ether/ep_openid_connect#readme",
   "dependencies": {
-    "openid-client": "^4.5.0"
+    "openid-client": "^4.7.4"
   },
   "devDependencies": {
-    "eslint": "^7.22.0",
-    "eslint-config-etherpad": "^1.0.26",
-    "eslint-plugin-cypress": "^2.11.2",
+    "eslint": "^7.32.0",
+    "eslint-config-etherpad": "^2.0.2",
+    "eslint-plugin-cypress": "^2.12.1",
     "eslint-plugin-eslint-comments": "^3.2.0",
-    "eslint-plugin-mocha": "^8.1.0",
+    "eslint-plugin-mocha": "^9.0.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prefer-arrow": "^1.2.3",
-    "eslint-plugin-promise": "^4.3.1",
-    "eslint-plugin-you-dont-need-lodash-underscore": "^6.11.0"
+    "eslint-plugin-promise": "^5.1.1",
+    "eslint-plugin-you-dont-need-lodash-underscore": "^6.12.0"
   },
   "eslintConfig": {
     "root": true,
@@ -46,12 +46,12 @@
   },
   "funding": {
     "type": "individual",
-    "url": "http://etherpad.org/"
+    "url": "https://etherpad.org/"
   },
   "peerDependencies": {
     "ep_etherpad-lite": ">=1.8.6"
   },
   "engines": {
-    "node": ">=10.13.0"
+    "node": ">=12.13.0"
   }
 }