summaryrefslogtreecommitdiff
path: root/docs/auth.rst
diff options
context:
space:
mode:
authorVictor Shyba <victor1984@riseup.net>2017-08-22 05:20:24 -0300
committerdrebs <drebs@riseup.net>2017-09-05 11:08:46 -0300
commite9fcab0981e343183345e90ab2c8a86e1b192b49 (patch)
treed63da6fda0e5038a11129150aa3bcd0cbeb7bc9d /docs/auth.rst
parent4ab64442b58ea96d746f7cb13af50f37b917c033 (diff)
[docs] add auth documentation from drebs draft
-- Related: #8867
Diffstat (limited to 'docs/auth.rst')
-rw-r--r--docs/auth.rst86
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) |
+ '-------------'