CAUTION: This is still totally in DRAFT and I might be losing the plot or missing things so your feedback is super welcome.

Check out the token protocol here: Request API token protocol

If we wish to authenticate in the fediverse seamlessly against any of the GraphQL protocol services out there, we need a simple way to proof that we are we across our APIs and services.

In traditional API’s this is done by sharing a secret and requesting authentication tokens that require you to make an account.

However, in the fediverse we want the API to validate that we are us without agreeing our secret or any form of prior interaction. Hence we can leverage something like asymmetric encryption and PGP to proof that we’re the one asking for authentication.

The first step is to have a well-known location for storing our public key. This public key will be used for verifying that the privately signed authentication requests are really coming from us. I have my public key hosted on GitHub for signing my commits. So if the API I am authenticating against think that this is trustworthy enough we’re good to go. Another option is storing it at keybase and checking those proofs. Either way, there needs to be some form of agreement on what trusted public PGP keys are.

So, in order to get authenticated, we break down our request in the following steps:

  1. Ask the API we wish to consume to give us a challenge. We provide the URL of the GPG key and the location URL of the GPG key, signed.
  2. The server can decide whether it even likes that location and whether it has enough trust. I.e. a keybase.Io location with some additional proofs is maybe more trustworthy than a random location. When it does decide to trust us, it starts downloading the public key, and verifies the signature with that key.
  3. If all is well, it will challenge us with a challenge-token. This challenge-token is used in order to prevent replay attacks. The token should be a nonce and thus can only be used once.
  4. If you sign that challenge with your private key again, you’ll get a token back and an expiry time. You can then communicate with that API as long as you don’t expire with that server using that token in the BEARER header.

After this, you can access the APIs that the server provides. Of course its up to the server to decide what permissions it allows you to use. An additional protocol is needed to grant you privileges.

So this works but has some down sides and attack vectors that might be interesting to talk about and would like some feedback on.

  • The key needs to be download from a well-known spot. If that URL is spoofed via DNS poisoning one could impersonate someone.
  • The consuming API can be DDOS’ed with downloading many keys and come to a halt.
  • The trusted location can be compromised allowing access to all services.
  • There needs to be a way to revoke tokens.

Please let me know if there is anything I am missing and discuss it here