From 7be2b776e4de9a46c1c6732bad46af1002758a67 Mon Sep 17 00:00:00 2001 From: Dennis Ciba Date: Sat, 20 Aug 2022 11:47:14 +0200 Subject: [PATCH 1/2] Create dedicated doc page on obtaining access tokens --- docs/configuring-playbook-bot-go-neb.md | 15 +----- ...ng-playbook-bot-matrix-registration-bot.md | 9 +--- docs/configuring-playbook-bot-maubot.md | 8 +-- docs/configuring-playbook-bot-mjolnir.md | 12 +---- ...ng-playbook-bridge-appservice-kakaotalk.md | 8 +-- ...iguring-playbook-bridge-mautrix-discord.md | 8 +-- ...guring-playbook-bridge-mautrix-facebook.md | 8 +-- ...ring-playbook-bridge-mautrix-googlechat.md | 8 +-- ...guring-playbook-bridge-mautrix-hangouts.md | 8 +-- ...figuring-playbook-bridge-mautrix-signal.md | 8 +-- ...guring-playbook-bridge-mautrix-telegram.md | 8 +-- ...guring-playbook-bridge-mautrix-whatsapp.md | 8 +-- docs/configuring-playbook-dimension.md | 22 +-------- docs/configuring-playbook-email2matrix.md | 13 +---- docs/maintenance-synapse.md | 9 +--- docs/obtaining-access-tokens.md | 49 +++++++++++++++++++ docs/updating-users-passwords.md | 2 +- 17 files changed, 65 insertions(+), 138 deletions(-) create mode 100644 docs/obtaining-access-tokens.md diff --git a/docs/configuring-playbook-bot-go-neb.md b/docs/configuring-playbook-bot-go-neb.md index 33ce4dd3..6ec2056c 100644 --- a/docs/configuring-playbook-bot-go-neb.md +++ b/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 diff --git a/docs/configuring-playbook-bot-matrix-registration-bot.md b/docs/configuring-playbook-bot-matrix-registration-bot.md index c47d5bfd..739f0869 100644 --- a/docs/configuring-playbook-bot-matrix-registration-bot.md +++ b/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 diff --git a/docs/configuring-playbook-bot-maubot.md b/docs/configuring-playbook-bot-maubot.md index d5990a11..1a6636d7 100644 --- a/docs/configuring-playbook-bot-maubot.md +++ b/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). diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index 5ddb2ad3..20760d5e 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/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 diff --git a/docs/configuring-playbook-bridge-appservice-kakaotalk.md b/docs/configuring-playbook-bridge-appservice-kakaotalk.md index 9ea7a3d1..127f18f4 100644 --- a/docs/configuring-playbook-bridge-appservice-kakaotalk.md +++ b/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` diff --git a/docs/configuring-playbook-bridge-mautrix-discord.md b/docs/configuring-playbook-bridge-mautrix-discord.md index 517fd9b4..9fbf1424 100644 --- a/docs/configuring-playbook-bridge-mautrix-discord.md +++ b/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` diff --git a/docs/configuring-playbook-bridge-mautrix-facebook.md b/docs/configuring-playbook-bridge-mautrix-facebook.md index 4429f004..d74ec2a3 100644 --- a/docs/configuring-playbook-bridge-mautrix-facebook.md +++ b/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` diff --git a/docs/configuring-playbook-bridge-mautrix-googlechat.md b/docs/configuring-playbook-bridge-mautrix-googlechat.md index 381d1f29..6527294b 100644 --- a/docs/configuring-playbook-bridge-mautrix-googlechat.md +++ b/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` diff --git a/docs/configuring-playbook-bridge-mautrix-hangouts.md b/docs/configuring-playbook-bridge-mautrix-hangouts.md index f6129777..49dad027 100644 --- a/docs/configuring-playbook-bridge-mautrix-hangouts.md +++ b/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` diff --git a/docs/configuring-playbook-bridge-mautrix-signal.md b/docs/configuring-playbook-bridge-mautrix-signal.md index f47640b9..403177e6 100644 --- a/docs/configuring-playbook-bridge-mautrix-signal.md +++ b/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` diff --git a/docs/configuring-playbook-bridge-mautrix-telegram.md b/docs/configuring-playbook-bridge-mautrix-telegram.md index 924de8ca..08ee83cc 100644 --- a/docs/configuring-playbook-bridge-mautrix-telegram.md +++ b/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 diff --git a/docs/configuring-playbook-bridge-mautrix-whatsapp.md b/docs/configuring-playbook-bridge-mautrix-whatsapp.md index 2af38be1..8ae6e5a0 100644 --- a/docs/configuring-playbook-bridge-mautrix-whatsapp.md +++ b/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` diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md index 73a7fc0e..b97be764 100644 --- a/docs/configuring-playbook-dimension.md +++ b/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.** diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index 510a9dcc..e1557d13 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/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 diff --git a/docs/maintenance-synapse.md b/docs/maintenance-synapse.md index 9727f450..a51811ff 100644 --- a/docs/maintenance-synapse.md +++ b/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. diff --git a/docs/obtaining-access-tokens.md b/docs/obtaining-access-tokens.md new file mode 100644 index 00000000..021d8589 --- /dev/null +++ b/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. + +There are two ways to generate an access token for a user, either 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, a random 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" +} +``` diff --git a/docs/updating-users-passwords.md b/docs/updating-users-passwords.md index 7d2f2832..2ea20d2f 100644 --- a/docs/updating-users-passwords.md +++ b/docs/updating-users-passwords.md @@ -34,7 +34,7 @@ where `` 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). From eb8551be190359a6ee9b0e8f3123592bed3c0ea7 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Sun, 21 Aug 2022 10:07:22 +0300 Subject: [PATCH 2/2] Improve wording and fix syntax trouble --- docs/obtaining-access-tokens.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/obtaining-access-tokens.md b/docs/obtaining-access-tokens.md index 021d8589..7db2ef1b 100644 --- a/docs/obtaining-access-tokens.md +++ b/docs/obtaining-access-tokens.md @@ -8,9 +8,9 @@ When setting up some optional features like bots and bridges you will need to pr 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. -There are two ways to generate an access token for a user, either 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. +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 +## Obtain an access token via Element 1. In a private browsing session (incognito window), open Element. 1. Log in with the user's credentials. @@ -29,13 +29,13 @@ You can use the following command to get an access token for your user directly curl -XPOST -d '{ "identifier": { "type": "m.id.user", "user": "USERNAME" }, "password": "PASSWORD", - "type": "m.login.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, a random ID will be generated. +`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):