User Tools

Site Tools


authentication

Server-to-server authentication

In order for instances to verify each other's identity, a weak authentication mechanism is used, based on a simple DNS dialback negotiation. The process goes roughly like this:

  1. Server A wants to prove its identity to Server B
  2. Server A tells Server B its dialback endpoint, via Server B's auth endpoint listed in its instance metadata
  3. Server B independently connects to the given endpoint and sends a secret token
  4. Server A, having received the secret, sends it back to Server B's auth endpoint
  5. Server B responds with an auth token, which Server A can use in subsequent requests to prove who it is

Note that the dialback process is unidirectional, meaning that it only verifies identity for one of the two instances (A in this example) and must be repeated in the other direction if needed.

In detail

Step 1. A sends a GET request to B's auth endpoint with the query parameters phase=dialback and target=<endpoint>, where <endpoint> is A's own dialback receiver endpoint. B does not need to send any response.

Step 2. B sends a POST request to the endpoint given by A in step 1, with the request body set to the application/x-www-form-urlencoded form data parameters origin=<host> and secret=<secret>, where <host> is B's hostname (including port number after a colon if needed) and <secret> is a cryptographically secure random string. A does not need to send any response.

Step 3. A, now knowing the secret given by B in step 2, sends another GET request to B's auth endpoint, this time with the query parameters phase=token and secret=<secret>. B responds with the JSON encoded data {“token”: “<token>”, “expires”: “<expiry>”}, where <token> is a new cryptographically secure random string and <expiry> is an ISO 8601 formatted timestamp for when the token will expire (indicating that A should refresh the token before this point).

todo: refreshing? errors? authenticated requests?

In diagram form

Server AServer AServer AServer BServer BServer BServer AServer AServer BServer BServer A wants to prove its identity with Server BGETServer B auth ?phase=dialback &target=<Server A dialback>202 Accepted / 204 No ContentPotentially some delayPOSTServer A dialback origin=Server B domain secret=<generated secret>202 Accepted / 204 No ContentGETServer B auth ?phase=token &secret=<generated secret from B>200 OK / 201 CreatedAuthenticated requestGETServer B whatever  Authentication: Bearer <token><whatever the response is>Server A wants to refresh the tokenA bit before the expires dateGETServer B auth ?phase=refresh  Authentication: Bearer <token>200 OK / 201 Created

are we sure that this can use different HTTP response codes? e.g. “200 OK / 201 Created” ? or would it be better to just pick one that should be used in all cases?

authentication.txt · Last modified: 2025/03/24 14:13 by winter