ep_openid_connect 2.0.9 → 2.3.0

package/README.md

@@ -52,10 +52,10 @@ 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`.
-* `displayname_claim` (optional; defaults to `"name"`): The claim containing the
-  name to display in the pad's user list.
-* `response_types` (optional; defaults to `["code"]`): List of OpenID Connect
-  response types.
+* `displayname_claim` (optional; defaults to `"name"`): The default value of
+  `user_properties.displayname.claim`. **Deprecated:** Set
+  `user_properties.displayname.claim` instead.
+* `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
@@ -64,6 +64,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
 
@@ -73,15 +76,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
     }
   },
@@ -92,6 +98,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,19 +5,29 @@ 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 settings = {
+const logger = log4js.getLogger('ep_openid_connect');
+const defaultSettings = {
   displayname_claim: 'name',
-  response_types: ['code'],
   permit_displayname_change: false,
   prohibited_usernames: ['admin', 'guest'],
+  scope: ['openid'],
+  user_properties: {},
 };
+const settings = {...defaultSettings};
 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();
 
+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
@@ -54,28 +64,40 @@ const getIssuer = async (settings) => {
   return new Issuer(settings.issuer_metadata);
 };
 
-exports.loadSettings = async (hookName, {settings: {[pluginName]: config = {}}}) => {
+exports.loadSettings = async (hookName, {settings: {ep_openid_connect: config = {}}}) => {
   Object.assign(settings, config);
   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 ${pluginName}.issuer or ${pluginName}.issuer_metadata must be set`);
+    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 ${pluginName}.issuer_metadata setting because ${pluginName}.issuer is set`);
+    logger.warn('Ignoring ep_openid_connect.issuer_metadata setting ' +
+                'because ep_openid_connect.issuer is set');
+  }
+  if (settings.response_types) {
+    logger.warn('Ignoring ep_openid_connect.response_types setting (it is no longer used)');
+    delete settings.response_types;
   }
   // Make sure base_url ends with '/' so that relative URLs are appended:
   if (!settings.base_url.endsWith('/')) settings.base_url += '/';
+  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'},
+  };
+  logger.debug('Settings:', {...settings, client_secret: '********'});
   oidcClient = new (await getIssuer(settings)).Client({
     client_id: settings.client_id,
     client_secret: settings.client_secret,
-    response_types: settings.response_types,
+    response_types: ['code'],
     redirect_uris: [endpointUrl('callback')],
   });
   logger.info('Configured.');
@@ -84,66 +106,102 @@ exports.loadSettings = async (hookName, {settings: {[pluginName]: config = {}}})
 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}`);
+      if (oidcClient == null) {
+        logger.warn('Not configured; ignoring request.');
+        return next();
+      }
       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.callbackChecks == null) throw new Error('missing authentication checks');
+      const tokenset =
+          await oidcClient.callback(endpointUrl('callback'), params, oidcSession.callbackChecks);
       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.callbackChecks;
       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 (oidcClient == null) {
+      logger.warn('Not configured; ignoring request.');
+      return next();
+    }
+    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()};
-    res.redirect(oidcClient.authorizationUrl(oidcSession.authParams));
+    const commonParams = {
+      nonce: generators.nonce(),
+      scope: settings.scope.join(' '),
+      state: generators.state(),
+    };
+    oidcSession.callbackChecks = {
+      ...commonParams,
+      code_verifier: generators.codeVerifier(), // RFC7636
+    };
+    res.redirect(oidcClient.authorizationUrl({
+      ...commonParams,
+      // RFC7636
+      code_challenge: generators.codeChallenge(oidcSession.callbackChecks.code_verifier),
+      code_challenge_method: 'S256',
+    }));
+  });
+  app.get(ep('logout'), (req, res, next) => {
+    logger.debug(`Processing ${req.url}`);
+    if (oidcClient == null) {
+      logger.warn('Not configured; ignoring request.');
+      return next();
+    }
+    req.session.destroy(() => res.redirect(settings.base_url));
   });
-  app.get(ep('logout'), (req, res) => req.session.destroy(() => res.redirect(settings.base_url)));
 };
 
 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;
 };
 
@@ -178,3 +236,7 @@ exports.preAuthorize = (hookName, {req}) => {
   if (req.path.startsWith(ep(''))) return true;
   return;
 };
+
+exports.exportedForTestingOnly = {
+  defaultSettings,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ep_openid_connect",
-  "version": "2.0.9",
+  "version": "2.3.0",
   "description": "Etherpad plugin to authenticate users against an OpenID Connect provider.",
   "main": "index.js",
   "repository": {
@@ -34,7 +34,9 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prefer-arrow": "^1.2.3",
     "eslint-plugin-promise": "^5.1.1",
-    "eslint-plugin-you-dont-need-lodash-underscore": "^6.12.0"
+    "eslint-plugin-you-dont-need-lodash-underscore": "^6.12.0",
+    "oidc-provider": "^7.10.6",
+    "supertest": "^6.1.6"
   },
   "eslintConfig": {
     "root": true,

package/static/tests/backend/login.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const assert = require('assert').strict;
+const common = require('ep_etherpad-lite/tests/backend/common');
+
+const logger = common.logger;
+
+const followRedirects = async (agent, res) => {
+  if (![302, 303].includes(res.status)) return res;
+  const url = new URL(res.headers.location, res.request.url);
+  logger.debug(`redirected to ${url}`);
+  return await followRedirects(agent, await agent.get(url));
+};
+
+// There might not be a set-cookie header on the response if the request sent a cookie and the
+// cookie value hasn't changed. If there is no set-cookie header, use the request's cookie.
+const fakeSetCookie = (jar, res) => {
+  if (!res.headers['set-cookie']) {
+    const url = new URL(res.request.url);
+    const cookies = jar.getCookies({
+      domain: url.hostname, // No port.
+      path: url.pathname,
+      secure: url.protocl === 'https:',
+      script: false,
+    }).toString();
+    if (cookies) res.headers['set-cookie'] = cookies;
+  }
+  return res;
+};
+
+module.exports = async (agent, issuer, startUrl, username) => {
+  // Visit the start URL and follow the redirects to the login page.
+  let res = await followRedirects(agent, await agent.get(startUrl));
+  const wantUrlBase = new URL('/interaction/', issuer).toString();
+  assert(res.request.url.startsWith(wantUrlBase),
+      `expected ${res.request.url} to start with ${wantUrlBase}`);
+  assert.equal(res.status, 200);
+
+  // Log in and follow redirects to the consent page.
+  logger.debug(`submitting login=${username}`);
+  res = await followRedirects(agent, await agent.get(`${res.request.url}?login=${username}`));
+  if (!res.request.url.startsWith(new URL('/interaction/', issuer).toString())) {
+    logger.debug('did not redirect to the consent page');
+    return fakeSetCookie(agent.jar, res);
+  }
+  assert.equal(res.status, 200);
+
+  // Indicate consent and follow redirects. (It should redirect back to the original URL, but that
+  // verification is done by the caller so that this function can be used to test error cases.)
+  logger.debug('submitting consent=true');
+  res = await followRedirects(agent, await agent.get(`${res.request.url}?consent=true`));
+  return fakeSetCookie(agent.jar, res);
+};

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

@@ -0,0 +1,143 @@
+'use strict';
+
+const MemoryAdapter = require('oidc-provider/lib/adapters/memory_adapter');
+const Provider = require('oidc-provider');
+const common = require('ep_etherpad-lite/tests/backend/common');
+const http = require('http');
+const util = require('util');
+
+const httpListen = util.promisify(http.Server.prototype.listen);
+const httpClose = util.promisify(http.Server.prototype.close);
+const logger = common.logger;
+
+// No-op subclass to silence warnings about using MemoryAdapter.
+class Adapter extends MemoryAdapter {}
+
+class OidcProvider {
+  async start(options) {
+    await this.stop();
+    this._server = http.createServer();
+    await httpListen.call(this._server, 0, 'localhost');
+    this.issuer = `http://localhost:${this._server.address().port}/`;
+    this._provider = new Provider(this.issuer, Object.assign({
+      adapter: Adapter,
+      claims: {
+        etherpad: [
+          'etherpad_is_admin',
+          'etherpad_readOnly',
+          'etherpad_canCreate',
+        ],
+      },
+      cookies: {
+        keys: [common.randomString()],
+      },
+      features: {
+        devInteractions: {enabled: false},
+      },
+      findAccount: async (ctx, sub, token) => ({
+        accountId: sub,
+        claims: async (use, scope, claims, rejected) => ({
+          sub,
+          etherpad_is_admin: sub.includes('admin'),
+          etherpad_readOnly: !sub.includes('admin') && sub.includes('readOnly'),
+          etherpad_canCreate:
+              sub.includes('admin') || (!sub.includes('readOnly') && !sub.includes('noCreate')),
+        }),
+      }),
+      jwks: {
+        /* eslint-disable max-len */
+        keys: [
+          {
+            d: 'VEZOsY07JTFzGTqv6cC2Y32vsfChind2I_TTuvV225_-0zrSej3XLRg8iE_u0-3GSgiGi4WImmTwmEgLo4Qp3uEcxCYbt4NMJC7fwT2i3dfRZjtZ4yJwFl0SIj8TgfQ8ptwZbFZUlcHGXZIr4nL8GXyQT0CK8wy4COfmymHrrUoyfZA154ql_OsoiupSUCRcKVvZj2JHL2KILsq_sh_l7g2dqAN8D7jYfJ58MkqlknBMa2-zi5I0-1JUOwztVNml_zGrp27UbEU60RqV3GHjoqwI6m01U7K0a8Q_SQAKYGqgepbAYOA-P4_TLl5KC4-WWBZu_rVfwgSENwWNEhw8oQ',
+            dp: 'E1Y-SN4bQqX7kP-bNgZ_gEv-pixJ5F_EGocHKfS56jtzRqQdTurrk4jIVpI-ZITA88lWAHxjD-OaoJUh9Jupd_lwD5Si80PyVxOMI2xaGQiF0lbKJfD38Sh8frRpgelZVaK_gm834B6SLfxKdNsP04DsJqGKktODF_fZeaGFPH0',
+            dq: 'F90JPxevQYOlAgEH0TUt1-3_hyxY6cfPRU2HQBaahyWrtCWpaOzenKZnvGFZdg-BuLVKjCchq3G_70OLE-XDP_ol0UTJmDTT-WyuJQdEMpt_WFF9yJGoeIu8yohfeLatU-67ukjghJ0s9CBzNE_LrGEV6Cup3FXywpSYZAV3iqc',
+            e: 'AQAB',
+            kty: 'RSA',
+            n: 'xwQ72P9z9OYshiQ-ntDYaPnnfwG6u9JAdLMZ5o0dmjlcyrvwQRdoFIKPnO65Q8mh6F_LDSxjxa2Yzo_wdjhbPZLjfUJXgCzm54cClXzT5twzo7lzoAfaJlkTsoZc2HFWqmcri0BuzmTFLZx2Q7wYBm0pXHmQKF0V-C1O6NWfd4mfBhbM-I1tHYSpAMgarSm22WDMDx-WWI7TEzy2QhaBVaENW9BKaKkJklocAZCxk18WhR0fckIGiWiSM5FcU1PY2jfGsTmX505Ub7P5Dz75Ygqrutd5tFrcqyPAtPTFDk8X1InxkkUwpP3nFU5o50DGhwQolGYKPGtQ-ZtmbOfcWQ',
+            p: '5wC6nY6Ev5FqcLPCqn9fC6R9KUuBej6NaAVOKW7GXiOJAq2WrileGKfMc9kIny20zW3uWkRLm-O-3Yzze1zFpxmqvsvCxZ5ERVZ6leiNXSu3tez71ZZwp0O9gys4knjrI-9w46l_vFuRtjL6XEeFfHEZFaNJpz-lcnb3w0okrbM',
+            q: '3I1qeEDslZFB8iNfpKAdWtz_Wzm6-jayT_V6aIvhvMj5mnU-Xpj75zLPQSGa9wunMlOoZW9w1wDO1FVuDhwzeOJaTm-Ds0MezeC4U6nVGyyDHb4CUA3ml2tzt4yLrqGYMT7XbADSvuWYADHw79OFjEi4T3s3tJymhaBvy1ulv8M',
+            qi: 'wSbXte9PcPtr788e713KHQ4waE26CzoXx-JNOgN0iqJMN6C4_XJEX-cSvCZDf4rh7xpXN6SGLVd5ibIyDJi7bbi5EQ5AXjazPbLBjRthcGXsIuZ3AtQyR0CEWNSdM7EyM5TRdyZQ9kftfz9nI03guW3iKKASETqX2vh0Z8XRjyU',
+            use: 'sig',
+          },
+          {
+            crv: 'P-256',
+            d: 'K9xfPv773dZR22TVUB80xouzdF7qCg5cWjPjkHyv7Ws',
+            kty: 'EC',
+            use: 'sig',
+            x: 'FWZ9rSkLt6Dx9E3pxLybhdM6xgR5obGsj5_pqmnz5J4',
+            y: '_n8G69C-A2Xl4xUW2lF0i8ZGZnk_KPYrhv4GbTGu5G4',
+          },
+        ],
+        /* eslint-enable max-len */
+      },
+      ttl: {
+        // Silence warnings.
+        AccessToken: 3600,
+        Grant: 3600,
+        IdToken: 3600,
+        Interaction: 3600,
+        Session: 3600,
+      },
+    }, options));
+    this._server.on('request', this._provider.callback());
+
+    // Install middleware that provides fake login and consent pages. This code would be prettier,
+    // but I wanted to avoid pulling in dependencies such as express or koa-route + koa-bodyparser.
+    this._provider.app.use(async (ctx, next) => {
+      const {request: {method, path, query}} = ctx;
+      if (!path.startsWith('/interaction/') || method !== 'GET') return await next();
+      const interactionDetails = await this._provider.interactionDetails(ctx.req, ctx.res);
+      if (Object.entries(query).length === 0) {
+        // This is where we would normally present a login or consent page. Just print the prompt
+        // name to help with debugging.
+        ctx.response.body = `waiting for ${interactionDetails.prompt.name}`;
+        ctx.response.status = 200;
+        return;
+      }
+      // Normally the login and consent pages would have a form that POSTs to the same URL, but for
+      // convenience this code just uses GET with a query parameter.
+      switch (interactionDetails.prompt.name) {
+        case 'login': {
+          const result = query.login.includes('fail')
+            ? {error: 'access_denied', error_description: 'injected failure'}
+            : {login: {accountId: query.login, remember: false}};
+          // This is test code; no need for username or password checking.
+          return await this._provider.interactionFinished(ctx.req, ctx.res, result);
+        }
+        case 'consent': {
+          // The amount of boilerplate code required to handle basic consent interaction is much
+          // higher than I would have expected. I don't understand this code; it is based on
+          // https://github.com/panva/node-oidc-provider/blob/039a55a0ab24cd4f6aa5831b829cfb2cc1337866/example/routes/express.js#L116-L152
+          const grant = interactionDetails.grantId
+            ? await this._provider.Grant.find(interactionDetails.grantId)
+            : new this._provider.Grant({
+              accountId: interactionDetails.session.accountId,
+              clientId: interactionDetails.params.client_id,
+            });
+          const {prompt: {details}} = interactionDetails;
+          if (details.missingOIDCScope) grant.addOIDCScope(details.missingOIDCScope.join(' '));
+          if (details.missingOIDCClaims) grant.addOIDCClaims(details.missingOIDCClaims);
+          if (details.missingResourceScopes) {
+            for (const [indicator, scopes] of Object.entries(details.missingResourceScopes)) {
+              grant.addResourceScope(indicator, scopes.join(' '));
+            }
+          }
+          const grantId = await grant.save();
+          return await this._provider.interactionFinished(ctx.req, ctx.res, {
+            consent: interactionDetails.grantId ? {} : {grantId},
+          });
+        }
+      }
+      return await next();
+    });
+
+    logger.info(`Test OpenID Connect provider listening at ${this.issuer}`);
+  }
+
+  async stop() {
+    if (this._server == null) return;
+    await httpClose.call(this._server);
+    this._server = null;
+  }
+}
+module.exports = OidcProvider;

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

@@ -0,0 +1,222 @@
+'use strict';
+
+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 padManager = require('ep_etherpad-lite/node/db/PadManager');
+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 pluginSettings = {
+    ...epOpenidConnect.exportedForTestingOnly.defaultSettings,
+    ...client,
+    // base_url and issuer will be filled in later.
+    scope: ['openid', 'etherpad'],
+    user_properties: {
+      is_admin: {claim: 'etherpad_is_admin'},
+      readOnly: {claim: 'etherpad_readOnly'},
+      canCreate: {claim: 'etherpad_canCreate'},
+    },
+  };
+  let socket;
+
+  before(async function () {
+    await common.init();
+    backup.settings = {...settings};
+    settings.requireAuthentication = true;
+    settings.requireAuthorization = false;
+    provider = new OidcProvider();
+    const clients =
+        [{...client, redirect_uris: [new URL('/ep_openid_connect/callback', common.baseUrl)]}];
+    await provider.start({clients});
+    issuer = provider.issuer;
+    pluginSettings.base_url = common.baseUrl;
+    pluginSettings.issuer = issuer;
+    await epOpenidConnect.loadSettings(
+        'loadSettings', {settings: {ep_openid_connect: pluginSettings}});
+  });
+
+  beforeEach(async function () {
+    agent = supertest.agent('');
+  });
+
+  afterEach(async function () {
+    if (socket != null) socket.close();
+    socket = null;
+  });
+
+  after(async function () {
+    if (provider != null) await provider.stop();
+    provider = null;
+    Object.assign(settings, backup.settings);
+  });
+
+  it('not logged in redirects to login endpoint', async function () {
+    const params = new URLSearchParams();
+    params.append('redirect_uri', new URL('/', common.baseUrl));
+    const wantRedirect = new URL(`/ep_openid_connect/login?${params}`, common.baseUrl).toString();
+    await agent.get(common.baseUrl)
+        .expect(302)
+        .expect('location', wantRedirect);
+  });
+
+  it('login endpoint redirects to authorization URL', async function () {
+    const params = new URLSearchParams();
+    params.append('redirect_uri', new URL('/', common.baseUrl));
+    await agent.get(new URL(`/ep_openid_connect/login?${params}`, common.baseUrl))
+        .expect(302)
+        .expect('location', /.*/)
+        .expect((res) => {
+          assert(res.headers.location.startsWith(`${new URL('/auth', issuer)}?`));
+          const location = new URL(res.headers.location);
+          const params = location.searchParams;
+          assert.deepEqual(params.getAll('redirect_uri'),
+              [new URL('/ep_openid_connect/callback', common.baseUrl).toString()]);
+          assert.deepEqual(params.getAll('client_id'), [pluginSettings.client_id]);
+          assert.deepEqual(params.getAll('response_type'), ['code']);
+          assert.deepEqual(params.getAll('scope'), [pluginSettings.scope.join(' ')]);
+          for (const param of ['code_challenge', 'nonce', 'state']) {
+            assert.equal(params.getAll(param).length, 1);
+            assert.notEqual(params.get(param), '');
+          }
+        });
+  });
+
+  it('normalUser can create and edit a pad', async function () {
+    const padId = common.randomString();
+    const url = new URL(`/p/${padId}`, common.baseUrl).toString();
+    const res = await login(agent, issuer, url, 'normalUser');
+    assert.equal(res.request.url, url); // Should have been redirected back after authenticating.
+    assert.equal(res.status, 200);
+    socket = await common.connect(res);
+    const msg = await common.handshake(socket, padId);
+    assert.equal(msg.type, 'CLIENT_VARS', `not a CLIENT_VARS message: ${JSON.stringify(msg)}`);
+    assert.equal(msg.data.readonly, false);
+  });
+
+  it('noCreate user is unable to create a pad', async function () {
+    const padId = common.randomString();
+    const url = new URL(`/p/${padId}`, common.baseUrl).toString();
+    const res = await login(agent, issuer, url, 'noCreate');
+    assert.equal(res.request.url, url); // Should have been redirected back after authenticating.
+    assert.equal(res.status, 200);
+    socket = await common.connect(res);
+    const message = await common.handshake(socket, padId);
+    assert.equal(message.accessStatus, 'deny');
+  });
+
+  it('noCreate user can edit an existing pad', async function () {
+    const padId = common.randomString();
+    await padManager.getPad(padId, 'this is a test');
+    assert(await padManager.doesPadExist(padId));
+    const url = new URL(`/p/${padId}`, common.baseUrl).toString();
+    const res = await login(agent, issuer, url, 'noCreate');
+    assert.equal(res.request.url, url); // Should have been redirected back after authenticating.
+    assert.equal(res.status, 200);
+    socket = await common.connect(res);
+    const msg = await common.handshake(socket, padId);
+    assert.equal(msg.type, 'CLIENT_VARS', `not a CLIENT_VARS message: ${JSON.stringify(msg)}`);
+    assert.equal(msg.data.readonly, false);
+  });
+
+  it('readOnly user is unable to create a pad', async function () {
+    const padId = common.randomString();
+    const url = new URL(`/p/${padId}`, common.baseUrl).toString();
+    const res = await login(agent, issuer, url, 'readOnly');
+    assert.equal(res.request.url, url); // Should have been redirected back after authenticating.
+    assert.equal(res.status, 200);
+    socket = await common.connect(res);
+    const message = await common.handshake(socket, padId);
+    assert.equal(message.accessStatus, 'deny');
+  });
+
+  it('readOnly user can view but not edit an existing pad', async function () {
+    const padId = common.randomString();
+    await padManager.getPad(padId, 'this is a test');
+    assert(await padManager.doesPadExist(padId));
+    const url = new URL(`/p/${padId}`, common.baseUrl).toString();
+    const res = await login(agent, issuer, url, 'readOnly');
+    assert.equal(res.request.url, url); // Should have been redirected back after authenticating.
+    assert.equal(res.status, 200);
+    socket = await common.connect(res);
+    const msg = await common.handshake(socket, padId);
+    assert.equal(msg.type, 'CLIENT_VARS', `not a CLIENT_VARS message: ${JSON.stringify(msg)}`);
+    assert.equal(msg.data.readonly, true);
+  });
+
+  it('authentication failure', async function () {
+    const res = await login(agent, issuer, new URL('/', common.baseUrl).toString(), 'fail');
+    assert.equal(res.status, 500);
+    const gotUrl = res.request.url;
+    const wantUrlBase = new URL('/ep_openid_connect/callback?', common.baseUrl).toString();
+    assert(gotUrl.startsWith(wantUrlBase), `expected ${gotUrl} to start with ${wantUrlBase}`);
+  });
+
+  describe('prohibited usernames', function () {
+    // The OIDC provider rejects '' as a username so that can't be tested here.
+    for (const username of [...pluginSettings.prohibited_usernames, '__proto__']) {
+      it(JSON.stringify(username), async function () {
+        const res = await login(agent, issuer, new URL('/', common.baseUrl).toString(), username);
+        assert(res.request.url.startsWith(new URL('/ep_openid_connect/callback?', common.baseUrl)));
+        assert.equal(res.status, 500);
+      });
+    }
+  });
+
+  describe('admin access', function () {
+    it('adminUser can access /admin/', async function () {
+      const url = new URL('/admin/', common.baseUrl).toString();
+      // Note that the username is "adminUser", not "admin", because "admin" is prohibited.
+      const res = await login(agent, issuer, url, 'adminUser');
+      assert.equal(res.request.url, url); // Should have been redirected back after authenticating.
+      assert.equal(res.status, 200);
+    });
+
+    it('normalUser is unable to access /admin/', async function () {
+      const url = new URL('/admin/', common.baseUrl).toString();
+      const res = await login(agent, issuer, url, 'normalUser');
+      assert.equal(res.request.url, url); // Should have been redirected back after authenticating.
+      assert.equal(res.status, 403);
+    });
+  });
+
+  it('visiting callback endpoint without session does not crash', async function () {
+    await agent.get(new URL('/ep_openid_connect/callback', common.baseUrl))
+        .expect(500);
+  });
+
+  it('visiting login endpoint directly redirects to base URL', async function () {
+    const url = new URL('/ep_openid_connect/login', common.baseUrl).toString();
+    const res = await login(agent, issuer, url, 'normalUser');
+    assert.equal(res.request.url, new URL('/', common.baseUrl).toString());
+    assert.equal(res.status, 200);
+  });
+
+  it('visiting logout endpoint destroys session, redirects to base URL', async function () {
+    const padId = common.randomString();
+    const url = new URL(`/p/${padId}`, common.baseUrl).toString();
+    const res = await login(agent, issuer, url, 'normalUser');
+    assert.equal(res.request.url, url);
+    assert.equal(res.status, 200);
+    await agent.get(new URL('/ep_openid_connect/logout', common.baseUrl))
+        .expect(302)
+        .expect('location', new URL('/', common.baseUrl).toString());
+    // Visiting any page that requires authentication should now redirect to the login page.
+    await agent.get(new URL('/', common.baseUrl))
+        .expect(302)
+        .expect('location', /./)
+        .expect((res) => assert(res.headers.location.startsWith(
+            new URL('/ep_openid_connect/login?', common.baseUrl).toString())));
+  });
+});