Merge pull request #2037 from DennisCiba/master

Create dedicated doc page on obtaining access tokens

docs/configuring-playbook-bot-go-neb.md

@@ -21,20 +21,7 @@ You can use the playbook to [register a new user](registering-users.md):
 ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
 ```
 
-
-## Getting an access token
-
-If you use curl, you can get an access token like this:
-
-```
-curl -X POST --header 'Content-Type: application/json' -d '{
-    "identifier": { "type": "m.id.user", "user": "bot.go-neb" },
-    "password": "a strong password",
-    "type": "m.login.password"
-}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
-```
-
-Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token), but doing so might lead to decryption problems. That warning comes from [here](https://github.com/matrix-org/go-neb#quick-start).
+Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
 
 
 ## Adjusting the playbook configuration

docs/configuring-playbook-bot-matrix-registration-bot.md

@@ -26,14 +26,7 @@ Choose a strong password for the bot. You can generate a good password with a co
 
 ## Obtaining an admin access token
 
-In order to use the bot you need to add an admin user's access token token to the configuration. As you created an admin user for the
-bot, it is recommended to obtain an access token by logging into Element/Schildichat with the bot account
-(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
-You can expand "Access token" to copy it.
-
-![Obatining an admin access token with Element](assets/obtain_admin_access_token_element.png)
-
-**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.
+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).
 
 ## Adjusting the playbook configuration
 

docs/configuring-playbook-bot-maubot.md

@@ -54,10 +54,4 @@ Choose a strong password for the bot. You can generate a good password with a co
 
 ## Obtaining an admin access token
 
-This can be done via `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)) or  by logging into Element/Schildichat with the bot account
-(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
-You can expand "Access token" to copy it.
-
-![Obatining an admin access token with Element](assets/obtain_admin_access_token_element.png)
-
-**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.
+This can be done via `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)). Alternatively, use Element or curl to [obtain an access token](obtaining-access-tokens.md).

docs/configuring-playbook-bot-mjolnir.md

@@ -24,17 +24,7 @@ If you would like Mjolnir to be able to deactivate users, move aliases, shutdown
 
 ## 2. Get an access token
 
-If you use curl, you can get an access token like this:
-
-```
-curl -X POST --header 'Content-Type: application/json' -d '{
-    "identifier": { "type": "m.id.user", "user": "bot.mjolnir" },
-    "password": "PASSWORD_FOR_THE_BOT",
-    "type": "m.login.password"
-}' 'https://matrix.DOMAIN/_matrix/client/r0/login'
-```
-
-Alternatively, you can use a full-featured client (such as Element) to log in and get the access token from there (note: don't log out from the client as that will invalidate the token).
+Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
 
 ## 3. Make sure the account is free from rate limiting

docs/configuring-playbook-bridge-appservice-kakaotalk.md

@@ -46,13 +46,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
-- retrieve a Matrix access token for yourself. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Appservice-Kakaotalk", "initial_device_display_name": "Appservice-Kakaotalk"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
 
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 

docs/configuring-playbook-bridge-mautrix-discord.md

@@ -60,13 +60,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
-- retrieve a Matrix access token for yourself. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Discord", "initial_device_display_name": "Mautrix-Discord"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
 
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 

docs/configuring-playbook-bridge-mautrix-facebook.md

@@ -58,13 +58,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
-- retrieve a Matrix access token for yourself. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Facebook", "initial_device_display_name": "Mautrix-Facebook"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
 
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 

docs/configuring-playbook-bridge-mautrix-googlechat.md

@@ -29,13 +29,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
-- retrieve a Matrix access token for yourself. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-googlechat", "initial_device_display_name": "Mautrix-googlechat"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
 
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 

docs/configuring-playbook-bridge-mautrix-hangouts.md

@@ -31,13 +31,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
-- retrieve a Matrix access token for yourself. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Hangouts", "initial_device_display_name": "Mautrix-Hangouts"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
 
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 

docs/configuring-playbook-bridge-mautrix-signal.md

@@ -73,13 +73,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
-- retrieve a Matrix access token for yourself. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Signal", "initial_device_display_name": "Mautrix-Signal"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
 
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 

docs/configuring-playbook-bridge-mautrix-telegram.md

@@ -28,13 +28,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
-- retrieve a Matrix access token for yourself. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Telegram", "initial_device_display_name": "Mautrix-Telegram"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
 
 - send `login-matrix` to the bot and follow instructions about how to send the access token to it
 

docs/configuring-playbook-bridge-mautrix-whatsapp.md

@@ -44,13 +44,7 @@ This is the recommended way of setting up Double Puppeting, as it's easier to ac
 
 When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
 
-- retrieve a Matrix access token for yourself. You can use the following command:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Mautrix-Whatsapp", "initial_device_display_name": "Mautrix-Whatsapp"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
+- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md).
 
 - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
 

docs/configuring-playbook-dimension.md

@@ -39,27 +39,7 @@ We recommend that you create a dedicated Matrix user for Dimension (`dimension`
 Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**.
 
 You are required to specify an access token (belonging to this new user) for Dimension to work.
-To get an access token for the Dimension user, you can follow one of two options:
-
-*Through an interactive login*:
-
-1. In a private browsing session (incognito window), open Element.
-1. Log in with the `dimension` user and its password.
-1. Set the display name and avatar, if required.
-1. In the settings page choose "Help & About", scroll down to the bottom and expand the `Access Token` section.
-1. Copy the access token to your configuration.
-1. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
-
-*With CURL*
-
-```
-curl -X POST --header 'Content-Type: application/json' -d '{
-    "identifier": { "type": "m.id.user", "user": "YourDimensionUsername" },
-    "password": "YourDimensionPassword",
-    "type": "m.login.password"
-}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
-```
-*Change `YourDimensionUsername`, `YourDimensionPassword`, and `YOURDOMAIN` accordingly.*
+To get an access token for the Dimension user, you can follow the documentation on [how to do obtain an access token](obtaining-access-tokens.md).
 
 **Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
 

docs/configuring-playbook-email2matrix.md

@@ -34,18 +34,7 @@ You'll need the room id when doing [Configuration](#configuration) below.
 
 ### Obtaining an access token for the sender user
 
-In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it.
-
-To do this, you can execute a command like this:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "email2matrix" }, "password": "MATRIX_PASSWORD_FOR_THE_USER", "type": "m.login.password", "device_id": "Email2Matrix", "initial_device_display_name": "Email2Matrix"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
-
-Take note of the `access_token` value. You'll need the access token when doing [Configuration](#configuration) below.
-
+In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
 ## Configuration
 

docs/maintenance-synapse.md

@@ -16,14 +16,7 @@ Table of contents:
 
 You can use the **[Purge History API](https://github.com/matrix-org/synapse/blob/master/docs/admin_api/purge_history_api.md)** to delete old messages on a per-room basis. **This is destructive** (especially for non-federated rooms), because it means **people will no longer have access to history past a certain point**.
 
-To make use of this API, **you'll need an admin access token** first. You can find your access token in the setting of some clients (like Element).
-Alternatively, you can log in and obtain a new access token like this:
-
-```
-curl \
---data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Synapse-Purge-History-API"}' \
-https://matrix.DOMAIN/_matrix/client/r0/login
-```
+To make use of this API, **you'll need an admin access token** first. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
 
 Synapse's Admin API is not exposed to the internet by default. To expose it you will need to add `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true` to your `vars.yml` file.
 

docs/obtaining-access-tokens.md

@@ -0,0 +1,49 @@
+# Obtaining an Access Token
+
+When setting up some optional features like bots and bridges you will need to provide an access token for some user. This document provides documentation on how to obtain such an access token.
+
+**Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.**
+
+## Prerequisites
+
+The user for whom you want to obtain an access token needs to already exist. You can use this playbook to [register a new user](registering-users.md), if you have not already.
+
+Below, we describe 2 ways to generate an access token for a user - using [Element](#obtain-an-access-token-via-element) or [curl](#obtain-an-access-token-via-curl). For both ways you need the user's password.
+
+## Obtain an access token via Element
+
+1. In a private browsing session (incognito window), open Element.
+1. Log in with the user's credentials.
+1. In the settings page, choose "Help & About", scroll down to the bottom and expand the `Access Token` section (see screenshot below).
+1. Copy the access token to your configuration.
+1. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work.
+
+![Obtaining an access token with Element](assets/obtain_admin_access_token_element.png)
+
+
+## Obtain an access token via curl
+
+You can use the following command to get an access token for your user directly from the [Matrix Client-Server API](https://www.matrix.org/docs/guides/client-server-api#login):
+
+```
+curl -XPOST -d '{
+    "identifier": { "type": "m.id.user", "user": "USERNAME" },
+    "password": "PASSWORD",
+    "type": "m.login.password",
+    "device_id": "YOURDEVICEID"
+}' 'https://matrix.YOURDOMAIN/_matrix/client/r0/login'
+```
+Change `USERNAME`, `PASSWORD`, and `YOURDOMAIN` accordingly.
+
+`YOURDEVICEID` is optional and can be used to more easily identify the session later. When omitted (mind the commas in the JSON payload if you'll be omitting it), a random device ID will be generated.
+
+Your response will look like this (prettified):
+
+```
+{
+    "user_id":"@USERNAME:YOURDOMAIN",
+    "access_token":">>>YOUR_ACCESS_TOKEN_IS_HERE<<<",
+    "home_server":"YOURDOMAIN",
+    "device_id":"YOURDEVICEID"
+}
+```

docs/updating-users-passwords.md

@@ -34,7 +34,7 @@ where `<password-hash>` is the hash returned by the docker command above.
 
 Use the Synapse User Admin API as described here: https://github.com/matrix-org/synapse/blob/master/docs/admin_api/user_admin_api.rst#reset-password
 
-This requires an access token from a server admin account. *This method will also log the user out of all of their clients while the other options do not.*
+This requires an [access token](obtaining-access-tokens.md) from a server admin account. *This method will also log the user out of all of their clients while the other options do not.*
 
 If you didn't make your account a server admin when you created it, you can use the `/usr/local/bin/matrix-change-user-admin-status` script as described in [registering-users.md](registering-users.md).