Move & document mrb password usage

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

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.
 

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,

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: ''

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"

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