summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordrebs <drebs@riseup.net>2017-09-14 11:57:48 -0300
committerdrebs <drebs@riseup.net>2017-09-14 12:04:56 -0300
commit93526deacfbc97e1e4abf5faa1a3c1bc3547f686 (patch)
treeff6e826c911888ec6d619025a6bf23f4657501c0
parent4946d4ec8c5a4fd26f5eef018bcc60442e9df737 (diff)
[doc] update documentation on authentication
- add server config file options for section [soledad-server] - fix services tokens file name - improve auth doc
-rw-r--r--docs/auth.rst30
-rw-r--r--docs/server.rst26
2 files changed, 46 insertions, 10 deletions
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.
+==================== =============================================== ================================