[docs] add auth documentation from drebs draft

-- Related: #8867

1 files changed, 86 insertions, 0 deletions

diff --git a/docs/auth.rst b/docs/auth.rst
new file mode 100644
index 00000000..06427a01
--- /dev/null
+++ b/docs/auth.rst
@@ -0,0 +1,86 @@
+Authentication
+==============
+
+.. contents::
+   :local:
+
+Authentication with the Soledad server is made using `Twisted's Pluggable
+Authentication system
+<https://twisted.readthedocs.io/en/latest/core/howto/cred.html>`_. The
+validation of credentials is performed by verifying a token provided by the
+client.
+
+There are currently two distinct authenticated entry points:
+
+* A public TLS encrypted **Users API**, providing the *Synchronization*,
+  *Blobs* and *Incoming* services, verified against the Leap Platform
+  ``tokens`` database.
+
+* A local plaintext **Services API**, providing the delivery part of the
+  *Incoming* service, authenticated against tokens defined in the server
+  configuration file.
+
+Authorization header
+--------------------
+
+The client has to provide a token encoded in an HTTP auth header, as in::
+
+    Authorization: Token <base64-encoded uuid:token>
+
+If no token is provided, the request is considered an "anonymous" request.
+Anonymous requests can only access `GET /`, which returns information about the
+server (as the version of the server and runtime configuration options).
+
+Special credentials for local services
+--------------------------------------
+
+Some special credentials can be configured in the Soledad Server configuration
+file. Currently, the only special credential provided is for the `/incoming`
+API, and defaults to the value `mx:default_mx_token`.
+
+If a credential header is sent in the request and the uuid is not one in a
+special credential configured in the Soledad Server configuration file, then a
+CouchDB database called `tokens` is consulted to check for a valid token.
+
+Implementation
+--------------
+
+Soledad Server package includes a systemd service file that spawns a ``twistd``
+daemon that loads a `.tac file
+<https://twistedmatrix.com/documents/12.2.0/core/howto/application.html#auto5>`_.
+When the server is started, two services are spawned:
+
+* A local entrypoint for services (serving on localhost only on port 2323).
+* A public entrypoint for users (serving on public IP on port 2424).
+
+.. code-block:: none
+
+    .------------------------------------------------------.
+    |                    soledad-server                    |
+    |      (twisted.application.service.Application)       |
+    '------------------------------------------------------'
+       |                                                |
+    .--------------.                      .----------------.
+    | 0.0.0.0:2424 |                      | 127.0.0.1:2323 |
+    |     (TLS)    |                      |     (TCP)      |
+    '--------------'                      '----------------'
+       |                                                |
+    .----------------.             .----------------------.
+    | Auth for users |             |  Auth for services   |
+    |  (UsersRealm)  |             | (LocalServicesRealm) |
+    '----------------'             '----------------------'
+       |                                                |
+    .------------------.        .-------------------------.
+    |    Users API     |        |      Services API       |
+    | (PublicResource) |        | (LocalServicesResource) |
+    '------------------'        '-------------------------'
+       |  .-------.                .-----------------.  |
+       '->| /sync |                |    /incoming    |<-'
+       |  '-------'                | (delivery only) |
+       |  .--------.               '-----------------'
+       '->| /blobs |
+       |  '--------'
+       |  .-------------.
+       '->|  /incoming  |
+          | (users API) |
+          '-------------'