From ad58698e0e82003327464ab7135822d6fe2609fc Mon Sep 17 00:00:00 2001 From: drebs Date: Thu, 28 Sep 2017 12:13:44 -0300 Subject: [doc] move auth to reference section --- docs/auth.rst | 93 ------------------------------------------------- docs/index.rst | 1 - docs/reference.rst | 1 + docs/reference/auth.rst | 93 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 94 insertions(+), 94 deletions(-) delete mode 100644 docs/auth.rst create mode 100644 docs/reference/auth.rst (limited to 'docs') diff --git a/docs/auth.rst b/docs/auth.rst deleted file mode 100644 index 07d8865c..00000000 --- a/docs/auth.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. _authentication: - -Authentication -============== - -.. contents:: - :local: - -Authentication with the Soledad server is made using `Twisted's Pluggable -Authentication system -`_. 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 - -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 -`_. -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 | - '-------- diff --git a/docs/index.rst b/docs/index.rst index c90a0bdb..ea723307 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,7 +15,6 @@ all user's devices that access a LEAP provider. client server - auth reference development migrations diff --git a/docs/reference.rst b/docs/reference.rst index 082d866c..a2b62c42 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -7,6 +7,7 @@ This page gathers reference documentation to understanding the internals of Sole :maxdepth: 1 reference/environment_variables + reference/auth reference/blobs reference/incoming_box reference/attachments 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 +`_. 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 + +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 +`_. +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 | + '-------- -- cgit v1.2.3