Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Document advising against publicly exposing the Admin API and provide a usage example #13231

Merged
merged 3 commits into from
Jul 13, 2022
Merged

Document advising against publicly exposing the Admin API and provide a usage example #13231

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a57dec9
Admin API request explanation improved
jejo86 Jul 8, 2022
4712657
Admin API request explanation improved
jejo86 Jul 8, 2022
7d51392
Apply suggestions from code review
DMRobertson Jul 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions changelog.d/13231.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Pointed out, that the Admin API is not accessible by default from any remote computer, but only from the PC `matrix-synapse` is running on.
Added a full, working example, making sure to include the cURL flag `-X`, which needs to be prepended to `GET`, `POST`, `PUT` etc. and listing the full query string including protocol, IP address and port.
DMRobertson marked this conversation as resolved.
Show resolved Hide resolved
10 changes: 10 additions & 0 deletions docs/usage/administration/admin_api/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,22 @@ already on your `$PATH` depending on how Synapse was installed.
Finding your user's `access_token` is client-dependent, but will usually be shown in the client's settings.

## Making an Admin API request
The Admin API (`/_synapse/admin/...`) is by default only accessible from within the host, so be sure to
call the queries from a terminal on the PC `matrix-synapse` is running on.
DMRobertson marked this conversation as resolved.
Show resolved Hide resolved

Once you have your `access_token`, you will need to authenticate each request to an Admin API endpoint by
providing the token as either a query parameter or a request header. To add it as a request header in cURL:

```sh
curl --header "Authorization: Bearer <access_token>" <the_rest_of_your_API_request>
```

For example, to query the information regarding the user '@foo:bar.com' call the following command in the terminal
using the access token 'syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk'.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hope this is not an access token belonging to a user on your homeserver. If so, you should revoke it immediately.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No it is a random string looking like a valid access token.

DMRobertson marked this conversation as resolved.
Show resolved Hide resolved

```sh
curl --header "Authorization: Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk" -X GET http://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.com
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably point out that 8008 might not work depending on how Synapse is configured to listen for requests.

```

For more details on access tokens in Matrix, please refer to the complete
[matrix spec documentation](https://matrix.org/docs/spec/client_server/r0.6.1#using-access-tokens).