You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
95 lines
2.3 KiB
Markdown
95 lines
2.3 KiB
Markdown
# Generic Mastodon Authenticator
|
|
Implementing oauth is boring. This service will take care of that for
|
|
you and your distributed mastodon app.
|
|
|
|
## How does it work
|
|
Your client connects to this server through a websocket connection.
|
|
|
|
### 1. Request authentication
|
|
Upon connection your client should send a message over the socket
|
|
containing the following json object:
|
|
|
|
```json
|
|
{
|
|
"type": "auth",
|
|
"parameters": {
|
|
"host": "YOUR_MASTODON_INSTANCE_HOSTNAME"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Validation
|
|
If the hostname you provided is a valid hostname, your client can skip
|
|
this step. If the hostname is incorrect, you will receive a message
|
|
containing the following json object:
|
|
|
|
```json
|
|
{
|
|
"type": "invalid-host",
|
|
"parameters": {}
|
|
}
|
|
```
|
|
|
|
You can then repeat step 1 until you have provided a valid hostname.
|
|
|
|
### 3. User authentication
|
|
If the hostname is valid, the server will accept the authentication
|
|
request and provide your client with a request ID. The json you
|
|
receive should look like this:
|
|
|
|
```json
|
|
{
|
|
"type": "set-id",
|
|
"arguments": {
|
|
"id": "THE REQUEST ID"
|
|
}
|
|
}
|
|
```
|
|
|
|
You can then compose a URL to redirect/point the user to. The url
|
|
should have the following format:
|
|
http(s)://your-auth-server.tld/auth/{ID} .
|
|
|
|
### 4. Request fulfillment
|
|
When the user logs in successfully and authorizes your app, your
|
|
client will receive one more json object with your access token. That
|
|
object will look like this:
|
|
|
|
```json
|
|
{
|
|
"type": "fulfill",
|
|
"parameters": {
|
|
"token": "THE ACCESS TOKEN"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Installation/Deployment
|
|
This server uses an embedded database so you won't have to worry about
|
|
setting one up. It also (as of right now) doesn't implement SSL, so it
|
|
is recommended to run it behind a reverse proxy that has SSL enabled
|
|
for your and your users' sake.
|
|
|
|
The configuration is done through a yaml file, here is an example:
|
|
|
|
```yaml
|
|
# The name of your application. This will be visible to users when authenticating.
|
|
app_name: example_app
|
|
|
|
# Your server's hostname
|
|
app_host: auth.example.com
|
|
|
|
# http scheme your app is hosted on
|
|
app_scheme: http
|
|
|
|
# Storage location for database file (make sure it is an absolute path)
|
|
db_path: /var/lib/generic-mastodon-authenticator/secrets.db
|
|
|
|
# Your application's website
|
|
website: https://example.com
|
|
|
|
# Scopes your app will need (see https://docs.joinmastodon.org/api/permissions/)
|
|
app_scopes:
|
|
- write:statuses
|
|
```
|