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) |
          '-------------'