Improve README
parent
eeae91426c
commit
2c17459d33
@ -1,3 +1,94 @@
|
||||
# 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
|
||||
```
|
||||
|
Loading…
Reference in New Issue