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.

2.3 KiB

Raw Permalink Blame History

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:

{
    "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:

{
    "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:

{
    "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:

{
    "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:

# 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

2.3 KiB Raw Permalink Blame History