summaryrefslogtreecommitdiff
path: root/docs/reference
diff options
context:
space:
mode:
Diffstat (limited to 'docs/reference')
-rw-r--r--docs/reference/auth.rst93
1 files changed, 93 insertions, 0 deletions
diff --git a/docs/reference/auth.rst b/docs/reference/auth.rst
new file mode 100644
index 00000000..07d8865c
--- /dev/null
+++ b/docs/reference/auth.rst
@@ -0,0 +1,93 @@
+.. _authentication:
+
+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* and
+ :ref:`blobs` services, verified against the Leap Platform
+ ``tokens`` database.
+
+* A local plaintext **Services API**, currently providing only the delivery
+ part of the *Incoming* service, authenticated against tokens defined in
+ a file specified on the server configuration file (see the
+ :ref:`services-tokens-file` section).
+
+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).
+
+.. _services-tokens-file:
+
+Services API tokens file
+------------------------
+
+Credentials for services accessible through the local Services API entrypoint
+can be added into a file, one in each line with the format
+``servicename:token``, like this::
+
+ incoming:Zm9yYSB0ZW1lciEK
+
+By default, Soledad Server will look for the tokens file in
+``/etc/soledad/services.tokens`` but that is configurable (see
+:ref:`server-config-file` for more information).
+
+Currently, the only special credential provided is for the *Incoming* service.
+
+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).
+* A public entrypoint for users (serving on public IP).
+* Localhost and public IP ports are configurable. Default is 2424 for public IP
+ and 2525 for localhost.
+
+.. code-block:: none
+
+ .------------------------------------------------------.
+ | soledad-server |
+ | (twisted.application.service.Application) |
+ '------------------------------------------------------'
+ | |
+ .--------------. .----------------.
+ | 0.0.0.0:2424 | | 127.0.0.1:2525 |
+ | (TLS) | | (TCP) |
+ '--------------' '----------------'
+ | |
+ .----------------. .----------------------.
+ | Auth for users | | Auth for services |
+ | (UsersRealm) | | (LocalServicesRealm) |
+ '----------------' '----------------------'
+ | |
+ .------------------. .-------------------------.
+ | Users API | | Services API |
+ | (PublicResource) | | (LocalResource) |
+ '------------------' '-------------------------'
+ | .-------. .-----------------. |
+ '->| /sync | | /incoming |<-'
+ | '-------' | (delivery only) |
+ | .--------. '-----------------'
+ '->| /blobs |
+ '--------