ep_openid_connect 2.0.9 → 2.1.1

package/README.md

@@ -52,10 +52,12 @@ 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.
+* `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
@@ -64,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
 
@@ -73,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
     }
   },
@@ -92,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,17 +5,18 @@ 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();
 
 const discoverIssuer = async (issuerUrl) => {
@@ -54,24 +55,31 @@ 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');
   }
   // 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'},
+  };
   oidcClient = new (await getIssuer(settings)).Client({
     client_id: settings.client_id,
     client_secret: settings.client_secret,
@@ -84,7 +92,7 @@ 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}) => {
@@ -94,15 +102,11 @@ exports.expressCreateServer = (hookName, {app}) => {
     logger.debug(`Processing ${req.url}`);
     (async () => {
       const params = oidcClient.callbackParams(req);
-      const oidcSession = req.session[pluginName] || {};
+      const oidcSession = req.session.ep_openid_connect || {};
       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 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;
+      oidcSession.userinfo = await oidcClient.userinfo(tokenset);
       // 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
@@ -117,10 +121,14 @@ exports.expressCreateServer = (hookName, {app}) => {
   });
   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)));
@@ -130,20 +138,31 @@ 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 {ep_openid_connect: {userinfo = {}} = {}} = session;
   const {sub} = userinfo;
-  if (sub == null) {
+  if (sub == null || // Nullish means the user isn't authenticated.
+      typeof sub !== 'string' || // `sub` is used as the username, so it must be a string.
+      sub === '' || // Empty string doesn't make sense.
+      sub === '__proto__' || // Prevent prototype pollution.
+      settings.prohibited_usernames.includes(sub)) {
     // Out of an abundance of caution, clear out the old state, nonce, and userinfo (if present) to
     // force regeneration.
-    delete session[pluginName];
+    delete session.ep_openid_connect;
     // Authn failed. Let another plugin try to authenticate the user.
     return;
   }
   // Successfully authenticated.
-  if (users[sub] == null) users[sub] = {};
+  logger.info('Successfully authenticated user with userinfo:', userinfo);
   session.user = users[sub];
-  session.user.username = sub;
-  session.user.displayname = userinfo[settings.displayname_claim] || session.user.displayname;
+  if (session.user == null) session.user = users[sub] = {};
+  for (const [propName, descriptor] of Object.entries(settings.user_properties)) {
+    if (descriptor.claim != null && descriptor.claim in userinfo) {
+      session.user[propName] = userinfo[descriptor.claim];
+    } else if ('default' in descriptor && !(propName in session.user)) {
+      session.user[propName] = descriptor.default;
+    }
+  }
+  logger.debug('User properties:', session.user);
   return true;
 };
 

package/package.json

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