{"id":28746153,"url":"https://github.com/ether/ep_openid_connect","last_synced_at":"2025-06-16T14:30:36.075Z","repository":{"id":36987319,"uuid":"307254139","full_name":"ether/ep_openid_connect","owner":"ether","description":"Etherpad plugin to authenticate users against an OpenID Connect provider","archived":false,"fork":false,"pushed_at":"2024-05-04T19:24:09.000Z","size":497,"stargazers_count":8,"open_issues_count":25,"forks_count":9,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-06-06T14:04:50.259Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ether.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-26T03:42:21.000Z","updated_at":"2025-04-13T19:12:06.000Z","dependencies_parsed_at":"2024-04-16T20:56:12.197Z","dependency_job_id":null,"html_url":"https://github.com/ether/ep_openid_connect","commit_stats":{"total_commits":172,"total_committers":5,"mean_commits":34.4,"dds":0.3081395348837209,"last_synced_commit":"7a8461ffef73e77a85ff90897df8d9c0134f78f7"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/ether/ep_openid_connect","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ether%2Fep_openid_connect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ether%2Fep_openid_connect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ether%2Fep_openid_connect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ether%2Fep_openid_connect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ether","download_url":"https://codeload.github.com/ether/ep_openid_connect/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ether%2Fep_openid_connect/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260175605,"owners_count":22970006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-16T14:30:35.166Z","updated_at":"2025-06-16T14:30:36.029Z","avatar_url":"https://github.com/ether.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Publish Status](https://github.com/ether/ep_openid_connect/workflows/Node.js%20Package/badge.svg) ![Backend Tests Status](https://github.com/ether/ep_openid_connect/workflows/Backend%20tests/badge.svg)\n\n# ep\\_openid\\_connect\n\nEtherpad plugin to authenticate users against an OpenID Connect provider.\n\nIt uses provider discovery to keep configuration simple.\n\nUnlike other auth plugins, this one is not based around passport, for\nsimplicity.\n\nThis is a fork of\n[ep\\_openid-client](https://github.com/stefanor/ep_openid-client).\n\n## Configuration\n\nThe plugin expects an `ep_openid_connect` block in the settings, with\nthis structure:\n\n```json\n  \"ep_openid_connect\": {\n    \"issuer\": \"https://id.example.com\",\n    \"client_id\": \"MY CLIENT ID\",\n    \"client_secret\": \"MY CLIENT SECRET\",\n    \"base_url\": \"https://pad.example.com\"\n  },\n  \"requireAuthentication\": true,\n```\n\nOAuth/OpenID Connect redirect URL (a.k.a. callback URL):\n`https://pad.example.com/ep_openid_connect/callback`\n\nEtherpad's `requireAuthentication` setting must be `true`.\n\n### Configuration Details\n\n* `issuer` (required if `issuer_metadata` is not set): The base URL of the\n  OpenID Connect identity provider, used to discover the relevant OpenID Connect\n  endpoints. If set, your identity provider must support the [OpenID Connect\n  Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)\n  protocol.\n* `issuer_metadata` (required if `issuer` is not set): Object containing details\n  about your OpenID Connect identity provider. Used for manual configuration if\n  your identity provider does not support the Discovery protocol. If your\n  identity provider does support Discovery, you are encouraged to set `issuer`\n  instead. For properties, see the [documentation for the openid-client `Issuer`\n  object\n  constructor](https://github.com/panva/node-openid-client/blob/v4.7.4/docs/README.md#new-issuermetadata).\n* `client_id` (required): The OAuth2 client ID issued by the identity provider.\n* `client_secret` (required): The OAuth2 client secret issued by the identity\n  provider.\n* `base_url` (required): The public base Etherpad URL. When registering Etherpad\n  with your identity provider, the redirect URL (a.k.a. callback URL) is this\n  base URL plus `/ep_openid_connect/callback`.\n* `scope` (optional; defaults to `[\"openid\"]`): List of OAuth2 scope strings.\n* `prohibited_usernames` (optional; defaults to `[\"admin\", \"guest\"]`): List of\n  strings that will trigger an authentication error if any match the `sub`\n  (subject) claim from the identity provider. Use this to avoid conflicts with\n  the users in the `users` setting and to avoid conflicts with other plugins\n  (such as [ep\\_guest](https://github.com/ether/ep_guest#readme)).\n* `user_properties` (optional): Object that controls the automatic creation of\n  additional properties on each authenticated user's account object. See below\n  for details.\n\n## Interaction with the `users` Setting\n\nWhen a user authenticates, the value of the `sub` (subject) claim is used as the\nuser's username in Etherpad. (The `sub` claim is the identity provider's unique\nidentifier for the user.) Many identity providers (such as GitLab) identify\nusers by a numeric user ID, so the `sub` claim (and thus the Etherpad username)\nwill probably look something like \"5374\".\n\nEach authenticated user gets their own account object. Default properties for a\nuser's account object come from the `users` setting in `settings.json`. Etherpad\nuses the `is_admin`, `readOnly`, and `canCreate` properties to control access,\nand the\n[ep\\_user\\_displayname](https://github.com/ether/ep_user_displayname#readme)\nplugin uses the `displayname` property for the name displayed in the user list.\nFor example, the following sets the default display name to \"Firstname Lastname\"\nand the default access to read-only for the user identified by \"5374\":\n\n```json\n  \"users\": {\n    \"5374\": {\n      \"displayname\": \"Firstname Lastname\",\n      \"readOnly\": true\n    }\n  },\n```\n\nTo avoid unintentionally applying values to users authenticated via this plugin,\nyou can use the `prohibited_usernames` settings to force an authentication error\nif the `sub` claim happens to match. This is useful for preventing a malicious\nidentity provider from gaining admin access to your Etherpad instance.\n\n### Controlling user account object properties with `user_properties`\n\nThe `user_properties` setting can be used to automatically add, remove, or\nchange properties on a user's account object when the user authenticates. The\n`user_properties` setting maps a property name to a descriptor object that\ndescribes how the property's value is obtained:\n\n  * If the descriptor object has a `claim` property that names an existing\n    OpenID Connect claim, the value is set to the value of the claim. (If there\n    is no such claim, `claim` has no effect.)\n  * If the descriptor object has a `default` property and the account object\n    property would otherwise be unset, the property is set to the given value.\n    (Note that a property set to `undefined` is not the same as unset.)\n  * If the descriptor object is `null`, the property is removed if present.\n\nFurthermore:\n\n  * If `user_properties` does not specifiy a descriptor for `displayname`, one\n    is added as follows:\n\n    ```json\n      \"ep_openid_connect\": {\n        \"user_properties\": {\n          \"displayname\": {\"claim\": \"name\"}\n        }\n      },\n    ```\n\n    You can cancel out this default behavior by explicitly specifying an empty\n    object:\n\n    ```json\n      \"ep_openid_connect\": {\n        \"user_properties\": {\n          \"displayname\": {}\n        }\n      },\n    ```\n\n  * The `username` property is described as follows and cannot be overridden or\n    canceled:\n\n    ```json\n      \"ep_openid_connect\": {\n        \"user_properties\": {\n          \"username\": {\"claim\": \"sub\"}\n        }\n      },\n    ```\n\nExample:\n\n```json\n  \"ep_openid_connect\": {\n    \"user_properties\": {\n      \"fromClaimWithDefault\": {\n        \"claim\": \"claimName\",\n        \"default\": \"default value\"\n      },\n      \"fromClaimOrUnset\": {\n        \"claim\": \"claimName\"\n      },\n      \"fixedValue\": {\n        \"default\": \"fixed value\"\n      },\n      \"forcedUnset\": null\n    }\n  },\n```\n\nThe above example sets properties as follows:\n* Each user's `fromClaimWithDefault` property is set to the value of the user's\n  `claimName` claim if present, otherwise the property is left unchanged if\n  already set, otherwise it is set to the string `\"default value\"`.\n* Each user's `fromClaimOrUnset` property is set to the value of the user's\n  `claimName` claim if present, otherwise the property is left unset/unchanged.\n* Each user's `fixedValue` property is set to the string `\"fixed value\"`\n  unless already set.\n* Each user's `forcedUnset` property is always deleted if present.\n* Each user's `displayname` property is set to to the value of the user's `name`\n  claim if present, otherwise the property is left unset/unchanged.\n* Each user's `username` property is set to the value of the `sub` claim.\n\nYou can use this feature to control access in the OpenID Connect provider if it\nprovides suitable claims:\n\n```json\n  \"ep_openid_connect\": {\n    \"scope\": [\"openid\", \"etherpad\"],\n    \"user_properties\": {\n      \"is_admin\": {\"claim\": \"etherpad_is_admin\"},\n      \"readOnly\": {\"claim\": \"etherpad_readOnly\"},\n      \"canCreate\": {\"claim\": \"etherpad_canCreate\"}\n    }\n  },\n```\n\nTo avoid breaking assumptions made by Etherpad, the `username` property cannot\nbe altered via the `user_properties` setting.\n\n## Interaction with the ep\\_guest Plugin\n\nThe [ep\\_guest](https://github.com/ether/ep_guest#readme) plugin creates a user\nthat is used for all guest accesses. It is recommended you add the username you\nchose for the guest user to the `prohibited_usernames` setting. If the identity\nprovider ever uses that username in the `sub` claim, you will get an obvious\nerror instead of a mysterious inability to edit pads.\n\n## Interaction with the ep\\_user\\_displayname Plugin\n\nBy default, this plugin sets the user's `displayname` property to the value of\nthe `name` claim. The\n[ep\\_user\\_displayname](https://github.com/ether/ep_user_displayname#readme)\nplugin uses this property (and the `displaynameChangeable` property) to control\nthe name displayed in the pad's list of users.\n\nYou can change the claim used to get the displayname:\n\n```json\n  \"ep_openid_connect\": {\n    \"user_properties\": {\n      \"displayname\": {\"claim\": \"nickname\"}\n    }\n  },\n```\n\nOr you can cancel the default behavior:\n\n\n```json\n  \"ep_openid_connect\": {\n    \"user_properties\": {\n      \"displayname\": {}\n    }\n  },\n```\n\n## Interaction with Etherpad's Built-in HTTP Basic Authentication\n\nIf the user has not yet successfully authenticated, this plugin defers the\naccess decision—it does not explicitly deny access. This causes Etherpad to fall\nback to another authentication plugin (if one is installed) or to the built-in\nHTTP basic authentication.\n\nNote: This plugin installs an authentication failure handler, so the user will\nnot get a 401 error that causes the browser to prompt for a username and\npassword for HTTP basic auth. To fall back to HTTP basic authentication, the\nuser's browser must proactively set the `Authorization: Basic \u003ccredentials\u003e`\nheader.\n\n## Interaction with Authorization Plugins\n\nThis plugin sets `req.session.user` to the user's settings object from\n`settings.json` and sets `req.session.user.username` to the user's username (the\n`sub` claim). Etherpad's built-in HTTP basic authentication does the same thing,\nso any authorization plugin designed to work with Etherpad's built-in\nauthentication should work with this plugin.\n\n## Support\n\nCurrently only tested against GitLab instances.\n\n## Copyright and License\n\nCopyright © 2020 Stefano Rivera \u003cstefano@rivera.za.net\u003e\\\nCopyright © 2020-2021 Richard Hansen \u003crhansen@rhansen.org\u003e\n\nLicensed under the [MIT/Expat license](LICENSE).\n\nThis is a fork of\n[ep\\_openid-client](https://github.com/stefanor/ep_openid-client) by Stefano\nRivera, which is based on\n[ep\\_oauth2](https://github.com/HumanBrainProject/ep_oauth2) and\n[ep\\_oidc](https://github.com/ToniIltanen/ep_oidc).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fether%2Fep_openid_connect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fether%2Fep_openid_connect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fether%2Fep_openid_connect/lists"}