====== 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:

  - Server A wants to prove its identity to Server B
  - Server A tells Server B its dialback endpoint, via Server B's ''auth'' endpoint listed in its [[instance metadata]]
  - Server B independently connects to the given endpoint and sends a secret token
  - Server A, having received the secret, sends it back to Server B's auth endpoint
  - 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).


<WRAP center round todo 60%>
todo: refreshing? errors? authenticated requests?
</WRAP>


===== In diagram form =====

<uml>
@startuml
skinparam responseMessageBelowArrow true


participant "Server A" as A
participant "Server B" as B
== Server A wants to prove its identity with Server B ==
A -> B: ""GET"" Server B auth \n\
 ""?phase=dialback""\n\
 ""&target=<Server A dialback>""
A <-- B: 202 Accepted / 204 No Content
...Potentially some delay...
B -> A: ""POST"" Server A dialback\n\
 ""origin=Server B domain""\n\
 ""secret=<generated secret>""
B <-- A: 202 Accepted / 204 No Content
A -> B: ""GET"" Server B auth\n\
 ""?phase=token""\n\
 ""&secret=<generated secret from B>""
A <-- B: 200 OK / 201 Created\n\
 {{json\n{\n\
 "token": "<token>",\n\
 "expires": "<date>"\n\
 }\n}}
== Authenticated request ==
A -> B: ""GET"" Server B whatever\n\
 <&header> ""Authentication: Bearer <token>""
A <-- B: <whatever the response is>
== Server A wants to refresh the token ==
...A bit before the expires date...
A -> B: ""GET"" Server B auth\n\
 ""?phase=refresh""\n\
 <&header> ""Authentication: Bearer <token>""

A <-- B: 200 OK / 201 Created\n\
 {{json\n{\n\
 "token": "<token>",\n\
 "expires": "<date>"\n\
 }\n}}
@enduml
</uml>

<WRAP center round todo 80%>
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?
</WRAP>