diff --git a/docs/configuring-playbook-appservice-double-puppet.md b/docs/configuring-playbook-appservice-double-puppet.md new file mode 100644 index 000000000..8f7d077ab --- /dev/null +++ b/docs/configuring-playbook-appservice-double-puppet.md @@ -0,0 +1,15 @@ +# Setting up Appservice Double Puppet (optional) + +Appservice Double Puppet is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver. + +This is useful for performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) via the [appservice method](https://docs.mau.fi/bridges/general/double-puppeting.html#appservice-method-new). The Appservice Double Puppet service is an implementation of this approach. + +Previously, bridges supported performing [double-puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but this old and hacky solution has been superseded by this Appservice Double Puppet method. + +To enable the Appservice Double Puppet service, adjust your `vars.yml` configuration like this and [re-run the playbook](./installing.md) (`just install-all`): + +```yml +matrix_appservice_double_puppet_enabled: true +``` + +When enabled, double puppeting will automatically be enabled for all bridges that support double puppeting via the appservice method. diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index e1ed4eb42..f971bb5d3 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -89,6 +89,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins ### Authentication and user-related +- [Setting up Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) (optional) + - [Setting up an ma1sd Identity Server](configuring-playbook-ma1sd.md) (optional) - [Setting up Synapse Admin](configuring-playbook-synapse-admin.md) (optional) diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 1894a3320..199669a0a 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -84,6 +84,8 @@ matrix_homeserver_container_extra_arguments_auto: | + (['--mount type=bind,src=' + matrix_appservice_draupnir_for_all_config_path + '/draupnir-for-all-registration.yaml,dst=/matrix-appservice-draupnir-for-all-registration.yaml,ro'] if matrix_appservice_draupnir_for_all_enabled else []) + + (['--mount type=bind,src=' + matrix_appservice_double_puppet_config_path + '/registration.yaml,dst=/matrix-appservice-double-puppet-registration.yaml,ro'] if matrix_appservice_double_puppet_enabled else []) + + (['--mount type=bind,src=' + matrix_appservice_irc_config_path + '/registration.yaml,dst=/matrix-appservice-irc-registration.yaml,ro'] if matrix_appservice_irc_enabled else []) + (['--mount type=bind,src=' + matrix_appservice_kakaotalk_config_path + '/registration.yaml,dst=/matrix-appservice-kakaotalk-registration.yaml,ro'] if matrix_appservice_kakaotalk_enabled else []) @@ -155,6 +157,8 @@ matrix_homeserver_app_service_config_files_auto: | + (['/matrix-appservice-draupnir-for-all-registration.yaml'] if matrix_appservice_draupnir_for_all_enabled else []) + + (['/matrix-appservice-double-puppet-registration.yaml'] if matrix_appservice_double_puppet_enabled else []) + + (['/matrix-appservice-irc-registration.yaml'] if matrix_appservice_irc_enabled else []) + (['/matrix-appservice-kakaotalk-registration.yaml'] if matrix_appservice_kakaotalk_enabled else []) @@ -2891,6 +2895,24 @@ matrix_appservice_draupnir_for_all_database_password: "{{ '%s' | format(matrix_h ###################################################################### +###################################################################### +# +# matrix-appservice-double-puppet +# +###################################################################### + +matrix_appservice_double_puppet_enabled: false + +matrix_appservice_double_puppet_registration_as_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'as.doub.pup', rounds=655555) | to_uuid }}" +matrix_appservice_double_puppet_registration_hs_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'hs.doub.pup', rounds=655555) | to_uuid }}" + +###################################################################### +# +# /matrix-appservice-double-puppet +# +###################################################################### + + ###################################################################### # # matrix-pantalaimon diff --git a/roles/custom/matrix-appservice-double-puppet/defaults/main.yml b/roles/custom/matrix-appservice-double-puppet/defaults/main.yml new file mode 100644 index 000000000..016b0f52c --- /dev/null +++ b/roles/custom/matrix-appservice-double-puppet/defaults/main.yml @@ -0,0 +1,38 @@ +matrix_appservice_double_puppet_enabled: true + +matrix_appservice_double_puppet_base_path: "{{ matrix_base_data_path }}/appservice-double-puppet" +matrix_appservice_double_puppet_config_path: "{{ matrix_appservice_double_puppet_base_path }}/config" + +matrix_appservice_double_puppet_registration_id: double-puppet +matrix_appservice_double_puppet_registration_url: ~ +matrix_appservice_double_puppet_registration_as_token: '' +matrix_appservice_double_puppet_registration_hs_token: '' +matrix_appservice_double_puppet_registration_sender_localpart: appservice-double-puppet + +matrix_appservice_double_puppet_registration_namespace_user_regex: "{{ '@.*:' + (matrix_domain | regex_escape) }}" + +# Default matrix-appservice-double-puppet registration configuration template which covers the generic use case. +# You can customize it by controlling the various variables inside it. +# +# For a more advanced customization, you can extend the default (see `matrix_appservice_double_puppet_registration_configuration_extension_yaml`) +# or completely replace this variable with your own template. +matrix_appservice_double_puppet_registration_configuration_yaml: "{{ lookup('template', 'templates/registration.yaml.j2') }}" + +matrix_appservice_double_puppet_registration_configuration_extension_yaml: | + # Your custom YAML configuration for matrix-appservice-double-puppet goes here. + # This configuration extends the default starting configuration (`matrix_appservice_double_puppet_registration_configuration_yaml`). + # + # You can override individual variables from the default configuration, or introduce new ones. + # + # If you need something more special, you can take full control by + # completely redefining `matrix_appservice_double_puppet_registration_configuration_yaml`. + # + # Example configuration extension follows: + # + # rate_limited: true + +matrix_appservice_double_puppet_registration_configuration_extension: "{{ matrix_appservice_double_puppet_registration_configuration_extension_yaml | from_yaml if matrix_appservice_double_puppet_registration_configuration_extension_yaml | from_yaml is mapping else {} }}" + +# Holds the final matrix-appservice-double-puppet configuration (a combination of the default and its extension). +# You most likely don't need to touch this variable. Instead, see `matrix_appservice_double_puppet_registration_configuration_yaml`. +matrix_appservice_double_puppet_registration_configuration: "{{ matrix_appservice_double_puppet_registration_configuration_yaml | from_yaml | combine(matrix_appservice_double_puppet_registration_configuration_extension, recursive=True) }}" diff --git a/roles/custom/matrix-appservice-double-puppet/tasks/install.yml b/roles/custom/matrix-appservice-double-puppet/tasks/install.yml new file mode 100644 index 000000000..c0818477b --- /dev/null +++ b/roles/custom/matrix-appservice-double-puppet/tasks/install.yml @@ -0,0 +1,23 @@ +--- + +- name: Ensure matrix-appservice-double-puppet paths exist + ansible.builtin.file: + path: "{{ item.path }}" + state: directory + mode: 0750 + owner: "{{ matrix_user_username }}" + group: "{{ matrix_user_groupname }}" + with_items: + - path: "{{ matrix_appservice_double_puppet_base_path }}" + when: true + - path: "{{ matrix_appservice_double_puppet_config_path }}" + when: true + when: item.when | bool + +- name: Ensure matrix-appservice-double-puppet registration configuration installed + ansible.builtin.copy: + content: "{{ matrix_appservice_double_puppet_registration_configuration | to_nice_yaml(indent=2, width=999999) }}" + dest: "{{ matrix_appservice_double_puppet_config_path }}/registration.yaml" + mode: 0644 + owner: "{{ matrix_user_username }}" + group: "{{ matrix_user_groupname }}" diff --git a/roles/custom/matrix-appservice-double-puppet/tasks/main.yml b/roles/custom/matrix-appservice-double-puppet/tasks/main.yml new file mode 100644 index 000000000..c7860d03b --- /dev/null +++ b/roles/custom/matrix-appservice-double-puppet/tasks/main.yml @@ -0,0 +1,20 @@ +--- + +- tags: + - setup-all + - setup-appservice-double-puppet + - install-all + - install-appservice-double-puppet + block: + - when: matrix_appservice_double_puppet_enabled | bool + ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml" + + - when: matrix_appservice_double_puppet_enabled | bool + ansible.builtin.include_tasks: "{{ role_path }}/tasks/install.yml" + +- tags: + - setup-all + - setup-appservice-double-puppet + block: + - when: not matrix_appservice_double_puppet_enabled | bool + ansible.builtin.include_tasks: "{{ role_path }}/tasks/uninstall.yml" diff --git a/roles/custom/matrix-appservice-double-puppet/tasks/uninstall.yml b/roles/custom/matrix-appservice-double-puppet/tasks/uninstall.yml new file mode 100644 index 000000000..cc22920cc --- /dev/null +++ b/roles/custom/matrix-appservice-double-puppet/tasks/uninstall.yml @@ -0,0 +1,6 @@ +--- + +- name: Ensure matrix-appservice-double-puppet paths don't exist + ansible.builtin.file: + path: "{{ matrix_appservice_double_puppet_base_path }}" + state: absent diff --git a/roles/custom/matrix-appservice-double-puppet/tasks/validate_config.yml b/roles/custom/matrix-appservice-double-puppet/tasks/validate_config.yml new file mode 100644 index 000000000..0151b1db1 --- /dev/null +++ b/roles/custom/matrix-appservice-double-puppet/tasks/validate_config.yml @@ -0,0 +1,10 @@ +--- +- name: Fail if required matrix-appservice-double-puppet settings not defined + ansible.builtin.fail: + msg: > + You need to define a required configuration setting (`{{ item.name }}`). + when: "item.when | bool and vars[item.name] == ''" + with_items: + - {'name': 'matrix_appservice_double_puppet_registration_as_token', when: true} + - {'name': 'matrix_appservice_double_puppet_registration_as_token', when: true} + - {'name': 'matrix_appservice_double_puppet_registration_sender_localpart', when: true} diff --git a/roles/custom/matrix-appservice-double-puppet/templates/registration.yaml.j2 b/roles/custom/matrix-appservice-double-puppet/templates/registration.yaml.j2 new file mode 100644 index 000000000..e3d19ee1f --- /dev/null +++ b/roles/custom/matrix-appservice-double-puppet/templates/registration.yaml.j2 @@ -0,0 +1,21 @@ +# The ID doesn't really matter, put whatever you want. +id: {{ matrix_appservice_double_puppet_registration_id | to_json }} +# The URL is intentionally left empty (null), as the homeserver shouldn't +# push events anywhere for this extra appservice. If you use a +# non-spec-compliant server, you may need to put some fake URL here. +url: {{ matrix_appservice_double_puppet_registration_url | to_json }} +# Generate random strings for these three fields. Only the as_token really +# matters, hs_token is never used because there's no url, and the default +# user (sender_localpart) is never used either. +as_token: {{ matrix_appservice_double_puppet_registration_as_token | to_json }} +hs_token: {{ matrix_appservice_double_puppet_registration_hs_token | to_json }} +sender_localpart: {{ matrix_appservice_double_puppet_registration_sender_localpart | to_json}} +# Bridges don't like ratelimiting. This should only apply when using the +# as_token, normal user tokens will still be ratelimited. +rate_limited: false +namespaces: + users: + # Replace your\.domain with your server name (escape dots for regex) + - regex: {{ matrix_appservice_double_puppet_registration_namespace_user_regex | to_json }} + # This must be false so the appservice doesn't take over all users completely. + exclusive: false diff --git a/setup.yml b/setup.yml index 5da953096..9f87f2acd 100644 --- a/setup.yml +++ b/setup.yml @@ -51,6 +51,7 @@ - galaxy/keydb - custom/matrix-corporal - custom/matrix-appservice-draupnir-for-all + - custom/matrix-appservice-double-puppet - custom/matrix-alertmanager-receiver - custom/matrix-bridge-appservice-discord - custom/matrix-bridge-appservice-slack