Skip to content

Commit 9e87e56

Browse files
GnuxieGnuxie
authored
Clarify how to create tokens and a draupnir account. (#84)
1 parent a4bc05c commit 9e87e56

File tree

2 files changed

+162
-48
lines changed

2 files changed

+162
-48
lines changed

‎.cspell-allowed-words‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ mxids
2525
neko
2626
nodesource
2727
nord
28+
localpart
2829
pantalaimon
2930
powerlevel
3031
precalculated

‎docs/bot/setup_draupnir_account.md‎

Lines changed: 161 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,197 @@
11
---
22
sidebar_position: 2
3-
sidebar_label: Creating an account for Draupnir
3+
sidebar_label: Creating an account and access token for Draupnir
44
---
55

6-
# Creating an account for Draupnir
6+
<!-- cspell:ignore XPOST -->
77

8-
:::tip
8+
# Creating an account and access token for Draupnir
99

10-
If you want Draupnir to be a homeserver admin, you might want to create
11-
the account using Synapse's `register_new_matrix_user` or Dendrite's `create-account` command.
12-
See the Synapse documentation [here](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html)
13-
and Dendrite documentation [here](https://element-hq.github.io/dendrite/administration/createusers#from-the-command-line).
10+
:::note
11+
12+
To deactivate users, move aliases, and shutdown rooms, Draupnir will need to be
13+
a server admin. These features are only supported on Synapse.
1414

1515
:::
1616

17-
If you are not using encrypted rooms anywhere, you can get an access
18-
token by opening Element in a separate browser profile or incognito
19-
tab and logging in as the bot or registering an account. Once you are
20-
logged in, go to "All Settings", "Help & About", and click the little
21-
triangle next to "Access token". Copy and paste that into your
22-
[config](./starting_draupnir) file under the `accessToken` key.
17+
:::info
2318

24-
:::note
19+
While Draupnir can be run on a rate limited account without issue. We recommend
20+
disabling rate limiting if the option is available to you. After you have
21+
created your account, you can see how to manage rate limiting
22+
[here](#disabling-rate-limiting).
2523

26-
Do not log out, just close the window, otherwise the access token
27-
will be invalidated.
24+
:::
2825

29-
If you have presence enabled on your homeserver, do not keep the
30-
window open or use the same session to login to the Draupnir account
31-
as this will cause you to accidentally trigger a bug in Synapse or
32-
Element web that will flood presence updates.
26+
## Pre-requisites
3327

34-
:::
28+
This page is going to tell you how to:
29+
30+
1. Create a fresh Matrix account for your Draupnir bot to use, optionally with
31+
server admin capabilities.
32+
2. Create an _access token_ for your bot to use to access the Matrix account.
33+
Which is an opaque string that you will paste into your
34+
[config](./starting_draupnir) file under the `accessToken` key (or via the
35+
`--access-token-path` option).
36+
3. Optionally disable rate limits for the account.
37+
4. Optionally turn an existing Synapse account into a synapse admin account.
38+
39+
## Creating an account
40+
41+
### Synapse
42+
43+
To create a new server admin account, you can use Synapse's
44+
`register_new_matrix_user` command. See the Synapse documentation for the
45+
[admin api](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html).
46+
47+
If you are using MAS (Element's
48+
[matrix-authentication-service](https://element-hq.github.io/matrix-authentication-service/index.html)),
49+
see how to register users using the
50+
[mas-cli](https://element-hq.github.io/matrix-authentication-service/reference/cli/manage.html#manage-register-user).
51+
52+
Once you have created an account proceed to
53+
[creating a token](#creating-a-token-all-homeservers).
54+
55+
### Dendrite
3556

36-
:::warning
57+
Please see the dendrite documentation for the `create-account` command
58+
[here](https://element-hq.github.io/dendrite/administration/createusers#from-the-command-line).
3759

38-
If you are using mas you cannot use the Synapse API currently.
60+
### Other or no server admin access
3961

40-
Instead you should use the mas-cli as such:
62+
Proceed to
63+
[creating an account or logging in with Element](#creating-an-account-or-logging-in-with-element).
64+
65+
## Creating a token (all homeservers)
66+
67+
### Creating a token with access to mas-cli
68+
69+
:::info
70+
71+
If you are deployed against a homeserver using MAS, but without access to the
72+
mas-cli, you will need to follow the instructions for
73+
[creating a token with curl](#getting-a-token-with-curl-mas-and-encryption-friendly).
74+
75+
:::
76+
77+
If you are using MAS, and you are a homeserver administrator, you will then need
78+
to create a token for Draupnir using `mas-cli`.
4179

4280
1. `mas-cli manage issue-compatibility-token --yes-i-want-to-grant-synapse-admin-privileges <username>`[^compat-token]
4381
1. `mas-cli manage provision-all-users` [^provision]
4482

45-
Note that this requires an existing account. Create this one as you usually would with MAS.
83+
Note that these two command require an existing account.
4684

47-
:::
85+
### Creating an account or logging in with Element
4886

49-
## Disabling rate limiting
87+
You should create an account or login by opening
88+
[Element](https://app.element.io) in a separate browser profile or incognito tab
89+
and registering an account for the bot.
90+
91+
### Getting a token from Element web
5092

5193
:::info
5294

53-
While Draupnir can be run on a rate limited account without issue. We
54-
recommend disabling rate limiting if the option is available to you.
95+
Do not copy the access token from Element web if your homeserver is using MAS
96+
(matrix-authentication-service). This includes bots deployed against matrix.org.
97+
Instead, you should use curl (see below). This is because the token Element web
98+
provisions expires very quickly. You can still register the user with Element
99+
however.
55100

56101
:::
57102

58-
By default, Draupnir will be rate limited by homeservers, which can
59-
inhibit Draupnir's ability to respond in some scenarios, particularly
60-
while redacting lots of messages.
103+
If your Draupnir is not configured to use Encryption, you can then, go to "All
104+
Settings", "Help & About", and click the little triangle next to "Access token".
105+
Copy and paste that into your [config](./starting_draupnir) file under the
106+
`accessToken` key.
61107

62-
It's therefore recommended to turn off ratelimiting for a draupnir
63-
bot, see [the synapse admin API
64-
documentation](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#set-ratelimit)
65-
for more information.
66-
For Dendrite this is configured in [dendrite.yaml](https://github.com/element-hq/dendrite/blob/main/dendrite-sample.yaml#L211)
67-
by adding `exempt_user_ids:` under `rate_limiting:`.
108+
Do not log out, just close the window, otherwise the access token will be
109+
invalidated.
68110

69-
## Making Draupnir a Synapse Admin
111+
If you have presence enabled on your homeserver, do not keep the window open or
112+
use the same session to login to the Draupnir account as this will cause you to
113+
accidentally trigger a bug in Synapse or Element web that will flood presence
114+
updates.
70115

71-
:::note
116+
### Getting a token with curl (MAS and Encryption friendly)
72117

73-
To deactivate users, move aliases, and shutdown rooms, Draupnir will
74-
need to be a server admin. These features are only supported on
75-
Synapse.
118+
To get an access token with curl, you will need three pieces of information.
76119

77-
:::
120+
1. The base url for client-server connections.
121+
2. Your draupnir user id localpart.
122+
3. Your draupnir user password.
123+
124+
#### Finding the base url
125+
126+
To find the base url for your homeserver, you will need to visit
127+
`https://example.com/.well-known/matrix/client` in your browser or with curl:
128+
129+
`curl https://example.com/.well-known/matrix/client`. You should see some JSON
130+
like this in response:
131+
132+
```
133+
{
134+
"m.homeserver": {
135+
"base_url": "https://matrix-client.example.com"
136+
}
137+
}
138+
```
139+
140+
The `base_url` under `m.homeserver` is your client-server base_url.
141+
142+
#### Finding the draupnir user id localpart
143+
144+
If your draupnir user matrix identifier is `@draupnir:example.com` the localpart
145+
will be `draupnir`.
146+
147+
#### Fetching the access token
148+
149+
To create the access token replace DRAUPNIR_LOCALPART, DRAUPNIR_USER_PASSWORD,
150+
and CLIENT_BASE_URL with the information gathered prior.
78151

79-
If you registered a new account, please see the Synapse documentation
80-
for how to make an existing account a Synapse admin
152+
```
153+
curl -XPOST -d '{
154+
"identifier": { "type": "m.id.user", "user": "DRAUPNIR_LOCALPART" },
155+
"password": "DRAUPNIR_USER_PASSWORD",
156+
"type": "m.login.password",
157+
}' 'CLIENT_BASE_URL/_matrix/client/r0/login'
158+
```
159+
160+
So that it should look like this:
161+
162+
```
163+
curl -XPOST -d '{
164+
"identifier": { "type": "m.id.user", "user": "draupnir" },
165+
"password": "********",
166+
"type": "m.login.password",
167+
}' 'https://matrix-client.example.com/_matrix/client/r0/login'
168+
```
169+
170+
You should get a response containing your access token.
171+
172+
## Disabling rate limiting
173+
174+
By default, Draupnir will be rate limited by homeservers, which can inhibit
175+
Draupnir's ability to respond in some scenarios, particularly while redacting
176+
lots of messages.
177+
178+
It's therefore recommended to turn off ratelimiting for a draupnir bot, see
179+
[the synapse admin API documentation](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#set-ratelimit)
180+
for more information. For Dendrite this is configured in
181+
[dendrite.yaml](https://github.com/element-hq/dendrite/blob/main/dendrite-sample.yaml#L211)
182+
by adding `exempt_user_ids:` under `rate_limiting:`.
183+
184+
## Making Draupnir a Synapse Admin
185+
186+
If you registered a new account, please see the Synapse documentation for how to
187+
make an existing account a Synapse admin
81188
[here](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html).
82189

83-
[^compat-token]: You can find more about it in the official documentation at [https://element-hq.github.io/matrix-authentication-service/reference/cli/manage.html#manage-issue-compatibility-token](https://element-hq.github.io/matrix-authentication-service/reference/cli/manage.html#manage-issue-compatibility-token)
84-
[^provision]: This ensures that synapse is aware of the user's new device. Otherwise synapse will reject requests. [Check upstream for more information](https://element-hq.github.io/matrix-authentication-service/reference/cli/manage.html#manage-provision-all-users)
190+
[^compat-token]:
191+
You can find more about it in the official documentation at
192+
[https://element-hq.github.io/matrix-authentication-service/reference/cli/manage.html#manage-issue-compatibility-token](https://element-hq.github.io/matrix-authentication-service/reference/cli/manage.html#manage-issue-compatibility-token)
193+
194+
[^provision]:
195+
This ensures that synapse is aware of the user's new device. Otherwise
196+
synapse will reject requests.
197+
[Check upstream for more information](https://element-hq.github.io/matrix-authentication-service/reference/cli/manage.html#manage-provision-all-users)

0 commit comments

Comments
 (0)