Improve README
parent
eeae91426c
commit
2c17459d33
@ -1,3 +1,94 @@
|
|||||||
# Generic Mastodon Authenticator
|
# Generic Mastodon Authenticator
|
||||||
Implementing oauth is boring. This service will take care of that for
|
Implementing oauth is boring. This service will take care of that for
|
||||||
you and your distributed mastodon app.
|
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