From 2ed0d2f8296e19e2966472edff234bc41a17727c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julian-Samuel=20Geb=C3=BChr?= Date: Mon, 5 Jun 2023 17:33:24 +0200 Subject: [PATCH] Move & document mrb password usage --- CHANGELOG.md | 8 ++++ ...ng-playbook-bot-matrix-registration-bot.md | 40 +++++++++---------- group_vars/matrix_servers | 6 +++ .../defaults/main.yml | 10 ++--- .../tasks/validate_config.yml | 9 +++-- .../templates/config/config.yml.j2 | 5 --- 6 files changed, 41 insertions(+), 37 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b5118427..d78a36bba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,11 @@ +# 2023-06-05 + +## matrix-registration-bot usage changed + +The matrix registration bot got some updates and supports password-based login. This means automatic registration is now possible and done by default. + +**For existing users** You need to set `matrix_bot_matrix_registration_bot_bot_password`. If previously only used `matrix_bot_matrix_registration_bot_bot_access_token` this was also used as `matrix_bot_matrix_registration_bot_api_token`. You now need to define the `api_token` explicitly while the `bot_access_token` is depreacted. You can therefore rename `matrix_bot_matrix_registration_bot_bot_access_token` -> `matrix_bot_matrix_registration_bot_api_token`. + # 2023-04-03 ## The matrix-jitsi role lives independently now diff --git a/docs/configuring-playbook-bot-matrix-registration-bot.md b/docs/configuring-playbook-bot-matrix-registration-bot.md index b1e3fdc6c..67892a1db 100644 --- a/docs/configuring-playbook-bot-matrix-registration-bot.md +++ b/docs/configuring-playbook-bot-matrix-registration-bot.md @@ -3,39 +3,34 @@ The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you. The bot allows you to easily **create and manage registration tokens**. It can be used for an invitation-based server, -where you invite someone by sending them a registration token. They can register as normal but have to provide a valid -registration token in a final step of the registration. +where you invite someone by sending them a registration token. They can register as normal but have to provide a valid registration token in a final step of the registration. See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it does and why it might be useful to you. -## Registering the bot user +## Configuration -By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:DOMAIN`. +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: -(to use a different username, adjust the `matrix_bot_matrix_registration_bot_matrix_user_id_localpart` variable). +For `matrix_bot_matrix_registration_bot_api_token`you need an access token with the permission to access the admin api. Access to the API is needed for all restricted actions of the bot (list, create etc..). Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). -For [other bots supported by the playbook](configuring-playbook.md#bots), Matrix bot user accounts are created and put to use automatically. For `matrix-registration-bot`, however, this is not the case - you **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md): - -``` -ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-registration-bot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user -``` - -Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`. - -## Obtaining an admin access token +```yaml +matrix_bot_matrix_registration_bot_enabled: true -In order to use the bot you need to add an admin user's access token token to the configuration. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). +# An access token with the permission to access the admin api. Access to the API is needed +# for all restricted actions of the bot (list, create etc..) +# Refer to the documentation on obtaining-access-tokens. +matrix_bot_matrix_registration_bot_api_token: "syt..." -## Adjusting the playbook configuration +#By default, the playbook will set use the bot with a username like +## this: `@bot.matrix-registration-bot:DOMAIN`. -Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: +# To use a different username, uncomment & adjust the variable. +# matrix_bot_matrix_registration_bot_matrix_user_id_localpart: bot.matrix-registration-bot -```yaml -matrix_bot_matrix_registration_bot_enabled: true -# Token obtained via logging into the bot account (see above) -matrix_bot_matrix_registration_bot_bot_access_token: "syt_bW9hbm9z_XXXXXXXXXXXXXr_2kuzbE" +# Generate a strong password here. Consider generating it with `pwgen -s 64 1` +matrix_bot_matrix_registration_bot_password: PASSWORD_FOR_THE_BOT # Enables registration matrix_synapse_enable_registration: true @@ -44,6 +39,7 @@ matrix_synapse_enable_registration: true matrix_synapse_registration_requires_token: true ``` +The bot account will be automatically created. ## Installing @@ -56,7 +52,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start ## Usage -To use the bot, create a **non-encrypted** room and invite `@bot.matrix-registration-bot:DOMAIN` (where `DOMAIN` is your base domain, not the `matrix.` domain). +To use the bot, message `@bot.matrix-registration-bot:DOMAIN` (where `DOMAIN` is your base domain, not the `matrix.` domain). In this room send `help` and the bot will reply with all options. diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index f25c4b4e1..704c27b2a 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -4001,6 +4001,12 @@ matrix_conduit_systemd_required_services_list: | matrix_user_creator_users_auto: | {{ + ([{ + 'username': matrix_bot_matrix_registration_bot_matrix_user_id_localpart, + 'initial_password': matrix_bot_matrix_registration_bot_bot_password, + 'initial_type': 'bot', + }] if matrix_bot_matrix_registration_bot_enabled else []) + + ([{ 'username': matrix_bot_matrix_reminder_bot_matrix_user_id_localpart, 'initial_password': matrix_bot_matrix_reminder_bot_matrix_user_password, diff --git a/roles/custom/matrix-bot-matrix-registration-bot/defaults/main.yml b/roles/custom/matrix-bot-matrix-registration-bot/defaults/main.yml index 152ebde58..1e4f9ef7f 100644 --- a/roles/custom/matrix-bot-matrix-registration-bot/defaults/main.yml +++ b/roles/custom/matrix-bot-matrix-registration-bot/defaults/main.yml @@ -21,17 +21,13 @@ matrix_bot_matrix_registration_bot_data_path: "{{ matrix_bot_matrix_registration matrix_bot_matrix_registration_bot_bot_server: "https://{{ matrix_server_fqn_matrix }}" matrix_bot_matrix_registration_bot_api_base_url: "https://{{ matrix_server_fqn_matrix }}" -# The access token that the bot uses to communicate in Matrix chats -# This does not necessarily need to be a privileged (admin) access token. -matrix_bot_matrix_registration_bot_bot_access_token: '' -# Instead also a password can be used + +# The bot's password (can also be used to login via a client like element) matrix_bot_matrix_registration_bot_bot_password: '' # The access token that the bot uses to call the Matrix API for creating registration tokens. # This needs to be a privileged (admin) access token. -# By default, we assume `matrix_bot_matrix_registration_bot_bot_access_token` is such a privileged token and we use it as is. -# If necessary, you can define your own other access token here, which might even be for a different Matrix user. -matrix_bot_matrix_registration_bot_api_token: "{{ matrix_bot_matrix_registration_bot_bot_access_token }}" +matrix_bot_matrix_registration_bot_api_token: '' matrix_bot_matrix_registration_bot_logging_level: info matrix_bot_matrix_registration_environment_variables_extension: '' diff --git a/roles/custom/matrix-bot-matrix-registration-bot/tasks/validate_config.yml b/roles/custom/matrix-bot-matrix-registration-bot/tasks/validate_config.yml index f5a3c7d60..b87204420 100644 --- a/roles/custom/matrix-bot-matrix-registration-bot/tasks/validate_config.yml +++ b/roles/custom/matrix-bot-matrix-registration-bot/tasks/validate_config.yml @@ -7,9 +7,12 @@ when: "vars[item] == ''" with_items: - "matrix_bot_matrix_registration_bot_api_token" + - "matrix_bot_matrix_registration_bot_bot_password" -- name: Fail if now bot secret is defined +- name: (Deprecation) Catch and report old settings ansible.builtin.fail: msg: >- - You need to define the bot secret to login. - when: "matrix_bot_matrix_registration_bot_bot_password == '' and matrix_bot_matrix_registration_bot_api_token ==''" + Your configuration contains a variable, which is deprecated - Please check the documentation on how to configure the matrix-registration-bot. + when: "item in vars" + with_items: + - "matrix_bot_matrix_registration_bot_bot_access_token" diff --git a/roles/custom/matrix-bot-matrix-registration-bot/templates/config/config.yml.j2 b/roles/custom/matrix-bot-matrix-registration-bot/templates/config/config.yml.j2 index 664a2fcbc..13abe6c7a 100644 --- a/roles/custom/matrix-bot-matrix-registration-bot/templates/config/config.yml.j2 +++ b/roles/custom/matrix-bot-matrix-registration-bot/templates/config/config.yml.j2 @@ -1,12 +1,7 @@ bot: server: {{ matrix_bot_matrix_registration_bot_bot_server|to_json }} username: {{ matrix_bot_matrix_registration_bot_matrix_user_id_localpart|to_json }} -{% if matrix_bot_matrix_registration_bot_bot_access_token | length > 0 %} - access_token: {{ matrix_bot_matrix_registration_bot_bot_access_token|to_json }} -{% endif %} -{% if matrix_bot_matrix_registration_bot_bot_password | length > 0 %} password: {{ matrix_bot_matrix_registration_bot_bot_password|to_json }} -{% endif %} api: # API endpoint of the registration tokens