{"id":18781572,"url":"https://github.com/devture/matrix-synapse-shared-secret-auth","last_synced_at":"2026-03-07T11:30:54.533Z","repository":{"id":33883107,"uuid":"145424926","full_name":"devture/matrix-synapse-shared-secret-auth","owner":"devture","description":"Shared Secret Authenticator password provider module for Matrix Synapse","archived":false,"fork":false,"pushed_at":"2024-01-06T15:36:15.000Z","size":64,"stargazers_count":87,"open_issues_count":3,"forks_count":15,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-06-28T14:43:28.461Z","etag":null,"topics":["matrix-org","python","synapse"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devture.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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":"2018-08-20T13:58:21.000Z","updated_at":"2025-03-20T20:24:47.000Z","dependencies_parsed_at":"2024-01-06T16:36:53.157Z","dependency_job_id":"9c78aa07-90c5-4367-829e-6235847ef424","html_url":"https://github.com/devture/matrix-synapse-shared-secret-auth","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/devture/matrix-synapse-shared-secret-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devture%2Fmatrix-synapse-shared-secret-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devture%2Fmatrix-synapse-shared-secret-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devture%2Fmatrix-synapse-shared-secret-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devture%2Fmatrix-synapse-shared-secret-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devture","download_url":"https://codeload.github.com/devture/matrix-synapse-shared-secret-auth/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devture%2Fmatrix-synapse-shared-secret-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30212124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T09:02:10.694Z","status":"ssl_error","status_checked_at":"2026-03-07T09:02:08.429Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["matrix-org","python","synapse"],"created_at":"2024-11-07T20:32:38.393Z","updated_at":"2026-03-07T11:30:54.498Z","avatar_url":"https://github.com/devture.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shared Secret Authenticator password provider module for Matrix Synapse\n\nShared Secret Authenticator is a password provider module that plugs into your [Matrix Synapse](https://github.com/matrix-org/synapse) homeserver.\n\nThe goal is to allow an external system to send a specially-crafted login request to Matrix Synapse and be able to obtain login credentials for any user on the homeserver.\n\nThis is useful when you want to:\n\n- use a bridge to another chat network which does double-puppeting and may need to impersonate your users from time to time\n- manage the state of your Matrix server (and its users) from an external system (your own custom code or via a tool like [matrix-corporal](https://github.com/devture/matrix-corporal))\n\nExample: you want your external system to auto-join a given user (`@user:example.com`) to some room. To do this, you need `@system:example.com` to invite `@user:example.com` to `!room:example.com` and then for the user to accept the invitation.\n\nTo do these, your external system needs to be able to log in with both `@system:example.com` and `@user:example.com` and perform actions on their behalf. You can have pre-generated access tokens (or keep a plain-text password) lying around for each user, but that's prone to breakage:\n\n- a pre-generated access token is annoying to create and can get revoked by the user at any time, leaving your external system unable to do anything.\n\n- keeping a plain-text password for all your users is cumbersome and not a good way to do things. Passwords can also get changed by the user at any time, leaving your external system unable to do anything.\n\nThis is where the Shared Secret Authenticator module comes to the rescue.\n\n\n## Installing\n\nIf you're using the [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy) Ansible playbook to install your homeserver and related services, you can also make it install this module too. See the [Setting up the Shared Secret Auth password provider module](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook-shared-secret-auth.md) documentation.\n\nOn [Archlinux](https://www.archlinux.org/), you can install one of these [AUR](https://wiki.archlinux.org/index.php/Arch_User_Repository) packages: [python-matrix-synapse-shared-secret-auth](https://aur.archlinux.org/packages/python-matrix-synapse-shared-secret-auth/) (latest tagged release) or [python-matrix-synapse-shared-secret-auth-git](https://aur.archlinux.org/packages/python-matrix-synapse-shared-secret-auth-git/).\n\nTo install and configure this manually, make sure `shared_secret_authenticator.py` is on the Python path, somewhere where the Matrix Synapse server can find it.\n\nThe easiest way is `pip install git+https://github.com/devture/matrix-synapse-shared-secret-auth` but you can also manually download `shared_secret_authenticator.py` from this repo to a path like `/usr/local/lib/python3.XXX/site-packages/shared_secret_authenticator.py` (adjust the `3.XXX` part of the path to match your Python version - e.g. `3.10`).\n\nSome distribution packages (such as the Debian packages from `matrix.org`) may use an isolated virtual environment, so you will need to install the library there. Any environments should be referenced in your init system - for example, the `matrix.org` Debian package creates a systemd init file at `/lib/systemd/system/matrix-synapse.service` that executes python from `/opt/venvs/matrix-synapse`.\n\nOnce installed, you can proceed to [Configuring](#configuring).\n\n\n### Using with Synapse running in a container\n\nTo use it with [Synapse](https://github.com/matrix-org/synapse) running in a container (for example, using the [matrixdotorg/synapse container image](https://hub.docker.com/r/matrixdotorg/synapse)), download the `shared_secret_authenticator.py` script from this repository and mount it into the container at a path like `/usr/local/lib/python3.11/site-packages/shared_secret_authenticator.py`.\n\nIf you're using `docker run` (`podman run`, etc.) to start your container, simply add `--mount type=bind,src=/HOST/PATH/TO/shared_secret_authenticator.py,dst=/usr/local/lib/python3.11/site-packages/shared_secret_authenticator.py` (or `-v /HOST/PATH/TO/shared_secret_authenticator.py:/usr/local/lib/python3.11/site-packages/shared_secret_authenticator.py`).\n\nOnce installed, you can proceed to [Configuring](#configuring).\n\n\n### Using with Synapse running under docker-compose\n\nIf you're using [docker-compose](https://docs.docker.com/compose/) to start the [Synapse](https://github.com/matrix-org/synapse) container, download the `shared_secret_authenticator.py` script from this repository and mount it into the container using a `volume` definition like this:\n\n```yaml\n  matrix:\n    image: matrixdotorg/synapse:latest\n    volumes:\n     - ./shared_secret_authenticator.py:/usr/local/lib/python3.11/site-packages/shared_secret_authenticator.py\n     ...\n```\n\nOnce installed, you can proceed to [Configuring](#configuring).\n\n\n## Configuring\n\nAs the name suggests, you need a \"shared secret\" (between this Matrix Synapse module and your external system).\n\nYou can generate a secure one with a command like this: `pwgen -s 128 1`.\n\nYou then need to edit Matrix Synapse's configuration (`homeserver.yaml` file) and enable the module:\n\n```yaml\nmodules:\n    - module: shared_secret_authenticator.SharedSecretAuthProvider\n      config:\n          shared_secret: \"YOUR_SHARED_SECRET_GOES_HERE\"\n\n          # By default, only login requests of type `com.devture.shared_secret_auth` are supported.\n          # Below, we explicitly enable support for the old `m.login.password` login type,\n          # which was used in v1 of matrix-synapse-shared-secret-auth and still widely supported by external software.\n          # If you don't need such legacy support, consider setting this to `false` or omitting it entirely.\n          m_login_password_support_enabled: true\n\n          # By default, only login requests of type `com.devture.shared_secret_auth` are supported.\n          #\n          # Uncomment the line below to disable `com.devture.shared_secret_auth` support.\n          # You will then need to:\n          # - have `m_login_password_support_enabled: true` to enable the `m.login.password` login type\n          # - authenticate using `m.login.password` requests, instead of ``com.devture.shared_secret_auth` requests\n          # com_devture_shared_secret_auth_support_enabled: false\n```\n\nThis uses the new **module** API (and `module` configuration key in `homeserver.yaml`), which added support for \"password providers\" in [Synapse v1.46.0](https://github.com/matrix-org/synapse/releases/tag/v1.46.0) (released on 2021-11-02). If you're running an older version of Synapse or need to use the old `password_providers` API, install an older version of matrix-synapse-sshared-secret-auth (`1.*` or the `v1-stable` branch).\n\nThe `m_login_password_support_enabled` configuration key enables support for the [`m.login.password`](https://matrix.org/docs/spec/client_server/r0.6.1#password-based) authentication type (the default that we used in **v1** of matrix-synapse-shared-secret-auth).\n\nThe `com_devture_shared_secret_auth_support_enabled` configuration key (having a `true` default value) can be used to disable our custom `com.devture.shared_secret_auth` authentication type. If you disable it, you will need to enable and use `m.login.password` login requests (see `m_login_password_support_enabled`).\n\nFor additional logging information, you might want to edit Matrix Synapse's `.log.config` file as well, adding a new logger:\n\n```\nloggers:\n    # other stuff here\n\n    shared_secret_authenticator:\n        level: INFO\n```\n\nYou need to restart Matrix Synapse for the module to start working.\n\n\n## Usage\n\nOnce installed and configured, you can obtain an access token for any user on your homeserver.\n\nExample code (in Python):\n\n```python\nimport json\nimport hmac\nimport hashlib\nimport requests\n\n\ndef obtain_access_token(full_user_id, homeserver_api_url, shared_secret):\n    login_api_url = homeserver_api_url + '/_matrix/client/r0/login'\n\n    token = hmac.new(shared_secret.encode('utf-8'), full_user_id.encode('utf-8'), hashlib.sha512).hexdigest()\n\n    payload = {\n        'type': 'com.devture.shared_secret_auth',\n        'identifier': {\n          'type': 'm.id.user',\n          'user': full_user_id,\n        },\n        'token': token,\n    }\n\n    # If `m_login_password_support_enabled`, you can use `m.login.password`.\n    # The token goes into the `password` field for this login type, not the `token` field.\n    #\n    # payload = {\n    #     'type': 'm.login.password',\n    #     'identifier': {\n    #       'type': 'm.id.user',\n    #       'user': full_user_id,\n    #     },\n    #     'password': token,\n    # }\n\n    response = requests.post(login_api_url, data=json.dumps(payload))\n\n    return response.json()['access_token']\n\n\nuser_id = \"@a:example.com\"\nhomeserver_api_url = \"https://matrix.example.com\"\nshared_secret = \"SECRET\"\n\naccess_token = obtain_access_token(user_id, homeserver_api_url, shared_secret)\nprint(access_token)\n```\n\nOnce your external system does its work with that accces token, it's best to clean up and revoke it (by hitting the appropriate `/logout` Matrix API routes).\n\n\n## FAQ\n\n### Can users still log in normally?\n\nYes.\n\nThis doesn't change the way normal log in happens.\nUsers would normally be authenticated by Matrix Synapse's database and the password stored in there.\n\nThis module merely provides an alternate way (a new `com.devture.shared_secret_auth` login type) that a user (or rather, some system on behalf of the user) could use to log in. It's completely separate from the other login flows (like `m.login.password`).\n\nIf you've enabled the old `m.login.password` login type via the `m_login_password_support_enabled` configuration setting (defaults to `false`, disabled) then this login type also gets handled. All regular password logins pass through this authentication module, and should they fail to complete, continue on their way to Synapse.\n\n\n### Can this be used in conjunction with other password providers?\n\nYes.\n\nMatrix Synapse will go through the list of password provider modules and try each matching one in turn.\nIt will stop only when it finds a password provider that successfully authenticates the user.\n\nBecause this password provider only does things locally and upon a direct \"password\" hit and other password providers (like the [HTTP JSON REST Authenticator](https://github.com/kamax-io/matrix-synapse-rest-auth)) may perform additional (and slower) tasks, for performance reasons it's better to put this one first in the `modules` list.\n\nIf you don't require backward compatibility (`m.login.password` support), we also suggest not enabling support for this login type (set `m_login_password_support_enabled` to `false` or skip this configuration option), which will improve performance.\n\n\n### This feels like an evil backdoor. Why would you do it?\n\nThis is meant to be used by server admins for administrating their server - data that they already host and own.\n\nThe easiest (and least intrusive) way to allow for such administration access is through such a special password provider.\n\nGaining a login session (as any user on the server) does not give the server admin access to anything they can't already access by inspecting the database manually.\nThanks to E2EE, messages in encrypted rooms remains private no matter how the server admin tries to read them.\n\n\n## How secure is this?\n\nIt uses a shared secret and [HMAC](https://en.wikipedia.org/wiki/HMAC), so it should be secure.\n\nIt doesn't use a nonce, so requests are replayable. The same request payload (user id + HMAC \"password\" combo) will always and forever authenticate you. That said, Matrix's `/login` endpoint suffers from the same deficiency by design (the same user id + password combo) will always and forever authenticate you.\n\nA future iteration of this module may put some timestamp information into the password value and reject requests from the past, thus making this even more secure.\n\nWith all that said, to the best of our knowledge, using this module (even as it is now), doesn't introduce any realistic security concern. If you know better, we'd be happy to hear from you.\n\n\n## Support\n\nMatrix room: [#matrix-synapse-shared-secret-auth:devture.com](https://matrix.to/#/#matrix-synapse-shared-secret-auth:devture.com)\n\nGithub issues: [devture/matrix-synapse-shared-secret-auth/issues](https://github.com/devture/matrix-synapse-shared-secret-auth/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevture%2Fmatrix-synapse-shared-secret-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevture%2Fmatrix-synapse-shared-secret-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevture%2Fmatrix-synapse-shared-secret-auth/lists"}