This chapter explains the high-level authentication flow from the perspective of a user and their client software.
The requirements from the user's point of view are simple: They want to be able to use a service as frictionless as possible. They are perhaps used to the concept of needing to obtain an API access key first in order to use a service, but do not necessarily want to register an account with their personal information to do so.
A service using the LSAT protocol supports exactly that requirement: The use of an API key without the need for creating an account first. And because no information needs to be input, the process of obtaining the API key can happen transparently to the user, in the background.
Whenever an LSAT-compatible client software connects to a server that uses the protocol, it receives a prompt to pay an invoice over a very small amount (a few satoshis). Once the client software pays that invoice (which can happen automatically if the amount does not exceed a user-defined threshold), a valid API key or authentication token can be constructed. That token is stored by the client's software and will be used for all future requests.
The following steps describe the diagram further below. It is the flow of calls that take place for a client software that wants to access a protected resource that is secured by an authentication server. As an example, we will look at the
loopdclient that wants to do a loop out swap with the Lightning Lab's loop server.
First time looping out:
- 1.A loop user wishes to perform a swap with the loop server. They type thecommand
loop out <amount>and hit return.
loopdclient program contacts the loop server to initiate the swap.
- 3.The call from the client must always go through the authentication serverreverse proxy, which in this example is
aperture. The authentication proxynotices that the client didn't send an LSAT and therefore cannot be grantedaccess to the loop server.
apertureinstructs its own
lndinstance to create an invoice over a smallamount that is required to acquire a fresh token.
- 5.In addition to the invoice,
aperturealso creates a fresh access token that istied to the invoice. The token is cryptographically constructed in a way thatit is only valid once the invoice has been paid.
- 6.The token and the invoice are sent back to the client in the previouslyunused HTTP header
402 Payment Required.
loopdunderstands this returned error code, extracts the invoice fromit and automatically instructs its connected
lndinstance to pay theinvoice.
- 8.Paying the invoice results in the
loopdclient now possessing thecryptographic proof of payment (the pre-image). This proof is stored in theclient's local storage, together with the access token.
- 9.The combination of the access token and the pre-image yields a fully validLSAT that can be cryptographically verified.
- 10.The client now repeats the original request to the loop server, nowattaching the LSAT to the request.
- 11.The authentication server intercepts the request, extracts the LSAT andvalidates it. Because the LSAT is valid, the request is forwarded to theactual loop server that then initiates the swap.
- 12.The answer of the swap server is returned to the client and the swap isnow initiated.
- 13.The whole process is fully transparent to the user. The only thing theymight notice is a short delay of a few seconds on the first ever loop. Eachsuccessive loop will use the same token and will not be delayed at all.
e2e flow sequence diagram
All further loops:
- 1.For every new request to the server, the client now automatically attachesthe token that is stored locally.
- 2.As long as the token has not expired, the steps 9-13 above will be followed.If/when the token expires, the server will start over at step 4 and instructthe client to obtain a fresh token.