From 93526deacfbc97e1e4abf5faa1a3c1bc3547f686 Mon Sep 17 00:00:00 2001
From: drebs <drebs@riseup.net>
Date: Thu, 14 Sep 2017 11:57:48 -0300
Subject: [doc] update documentation on authentication

- add server config file options for section [soledad-server]
- fix services tokens file name
- improve auth doc
---
 docs/auth.rst   | 30 ++++++++++++++++++++----------
 docs/server.rst | 26 ++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 10 deletions(-)

(limited to 'docs')

diff --git a/docs/auth.rst b/docs/auth.rst
index 5a0dcc94..26a89b6f 100644
--- a/docs/auth.rst
+++ b/docs/auth.rst
@@ -16,9 +16,10 @@ There are currently two distinct authenticated entry points:
   *Blobs* 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 a file specified
-  on the server configuration file.
+* 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
 --------------------
@@ -31,13 +32,22 @@ 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
---------------------------------------
+.. _services-tokens-file:
 
-Some special credentials can be added into a file
-(``/etc/soledad/incoming.tokens``, by default) and then configured in the
-Soledad Server configuration file. Currently, the only special credential
-provided is for the `/incoming` API.
+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
 --------------
@@ -78,4 +88,4 @@ When the server is started, two services are spawned:
        |  '-------'                | (delivery only) |
        |  .--------.               '-----------------'
        '->| /blobs |
-          '--------'
+          '--------
diff --git a/docs/server.rst b/docs/server.rst
index 2317908d..88bf909f 100644
--- a/docs/server.rst
+++ b/docs/server.rst
@@ -67,3 +67,29 @@ This has some implications:
 The authorization for creating, updating, deleting and retrieving recovery
 documents on the shared database is handled by `leap.soledad.server.auth`
 module.
+
+.. _server-config-file:
+
+Server Configuration File
+-------------------------
+
+Soledad Server looks for a configuration file in
+``/etc/soledad/soledad-server.conf`` and will read the following configuration
+options from the ``[soledad-server]`` section:
+
+==================== =============================================== ================================
+Option               Description                                     Default value
+==================== =============================================== ================================
+couch_url            The URL of the CouchDB backend storage.         ``http://localhost:5984``
+create_cmd           The shell command to create user databases.     None
+admin_netrc          The netrc file to be used for authenticating    ``/etc/couchdb/couchdb.netrc``
+                     with the CouchDB backend storage.
+batching             Whether to use batching capabilities for        ``true``
+                     synchronization.
+blobs                Whether to provide the Blobs functionality or   ``false``
+                     not.
+blobs_path           The path for blobs storage in the server's file ``/var/lib/soledad/blobs``
+                     system.
+services_tokens_file The file containing authentication tokens for   ``/etc/soledad/services.tokens``
+                     services provided through the Services API.
+==================== =============================================== ================================
-- 
cgit v1.2.3