diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/auth.rst | 86 | ||||
| -rw-r--r-- | docs/index.rst | 1 |
2 files changed, 87 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) | + '-------------' diff --git a/docs/index.rst b/docs/index.rst index 3e200d48..722aeeda 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ all user's devices that access a LEAP provider. client server + auth reference development |