Ep_openid_connect NPM

ep_openid_connect

Etherpad plugin to authenticate users against an OpenID Connect provider.

It uses provider discovery to keep configuration simple.

Unlike other auth plugins, this one is not based around passport, for simplicity.

Configuration

The plugin expects an ep_openid_connect block in the settings, with this structure:

  "ep_openid_connect": {
    "issuer": "https://id.example.com",
    "client_id": "MY CLIENT ID",
    "client_secret": "MY CLIENT SECRET",
    "base_url": "https://pad.example.com"
  },
  "requireAuthentication": true,

OAuth/OpenID Connect redirect URL (a.k.a. callback URL): https://pad.example.com/ep_openid_connect/callback

Etherpad's requireAuthentication setting must be true.

Configuration Details

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 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.
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.
scope (optional; defaults to ["openid"]): List of OAuth2 scope strings.
prohibited_usernames (optional; defaults to ["admin", "guest"]): List of strings that will trigger an authentication error if any match the sub (subject) claim from the identity provider. Use this to avoid conflicts with the users in the users setting and to avoid conflicts with other plugins (such as ep_guest).
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

When a user authenticates, the value of the sub (subject) claim is used as the user's username in Etherpad. (The sub claim is the identity provider's unique 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".

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 the ep_user_displayname 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":

  "users": {
    "5374": {
      "displayname": "Firstname Lastname",
      "readOnly": true
    }
  },

To avoid unintentionally applying values to users authenticated via this plugin, 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.

Controlling user account object properties with `user_properties`

The user_properties setting can be used to automatically add, remove, or change properties on a user's account object when the user authenticates. The user_properties setting maps a property name to a descriptor object that 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 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.)
If the descriptor object is null, the property is removed if present.

Furthermore:

If user_properties does not specifiy a descriptor for displayname, one is added as follows:

  "ep_openid_connect": {
    "user_properties": {
      "displayname": {"claim": "name"}
    }
  },

You can cancel out this default behavior by explicitly specifying an empty object:

  "ep_openid_connect": {
    "user_properties": {
      "displayname": {}
    }
  },

The username property is described as follows and cannot be overridden or canceled:

  "ep_openid_connect": {
    "user_properties": {
      "username": {"claim": "sub"}
    }
  },

Example:

  "ep_openid_connect": {
    "user_properties": {
      "fromClaimWithDefault": {
        "claim": "claimName",
        "default": "default value"
      },
      "fromClaimOrUnset": {
        "claim": "claimName"
      },
      "fixedValue": {
        "default": "fixed value"
      },
      "forcedUnset": null
    }
  },

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.
Each user's forcedUnset property is always deleted if present.
Each user's displayname property is set to to the value of the user's name claim if present, otherwise the property is left unset/unchanged.
Each user's username property is set to the value of the sub claim.

You can use this feature to control access in the OpenID Connect provider if it provides suitable claims:

  "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_guest Plugin

The ep_guest plugin creates a user that is used for all guest accesses. It is recommended you add the username you chose for the guest user to the prohibited_usernames setting. If the identity provider ever uses that username in the sub claim, you will get an obvious error instead of a mysterious inability to edit pads.

Interaction with the ep_user_displayname Plugin

By default, this plugin sets the user's displayname property to the value of the name claim. The ep_user_displayname plugin uses this property (and the displaynameChangeable property) to control the name displayed in the pad's list of users.

You can change the claim used to get the displayname:

  "ep_openid_connect": {
    "user_properties": {
      "displayname": {"claim": "nickname"}
    }
  },

Or you can cancel the default behavior:

  "ep_openid_connect": {
    "user_properties": {
      "displayname": {}
    }
  },

Interaction with Etherpad's Built-in HTTP Basic Authentication

If the user has not yet successfully authenticated, this plugin defers the access decision—it does not explicitly deny access. This causes Etherpad to fall back to another authentication plugin (if one is installed) or to the built-in HTTP basic authentication.

Note: This plugin installs an authentication failure handler, so the user will not get a 401 error that causes the browser to prompt for a username and password for HTTP basic auth. To fall back to HTTP basic authentication, the user's browser must proactively set the Authorization: Basic <credentials> header.

Interaction with Authorization Plugins

This plugin sets req.session.user to the user's settings object from settings.json and sets req.session.user.username to the user's username (the sub claim). Etherpad's built-in HTTP basic authentication does the same thing, so any authorization plugin designed to work with Etherpad's built-in authentication should work with this plugin.