DOC: Authentication updated.

src/doc/specification/Authentication.rst

+==============
 Authentication
 ==============
 
-Some features of CaosDB are available to registered users only. Making any
-changes to the data stock via HTTP requires authentication by ``username`` **plus**
-``password``. They are to be send as a HTTP header, while the password is to be
-hashed by the sha512 algorithm:
-
-============= ======================
-username:     password:
-============= ======================
-``$username`` ``$SHA512ed_password``
-============= ======================
+Some features of CaosDB are available to registered users only. Making any changes to the data stock
+via HTTP requires authentication.
 
 Sessions
---------
+========
 
 Login
-^^^^^
+-----
+
+Authentication is done by ``username`` and ``password``. They must be sent as form data with a POST
+request to the `/login/` resource:
+
+username:
+  The user name, for example ``admin`` (on demo.indiscale.com).
+
+password:
+  The password, for example ``caosdb`` (on demo.indiscale.com).
+
+Logout
+------
+
+Send
+
+``GET http://host:port/logout``
+
+with a valid AuthToken cookie. No new AuthToken will be returned and no AuthToken with that session
+will be accepted anymore.
+
+Example using ``curl``
+----------------------
+
+.. _curl-login:
+
+Login
+~~~~~
+
+To use curl for talking with the server, first save your password into a
+variable: ``PW=$(cat)``
+
+The create a cookie in ``cookie.txt`` like this (note that this makes your
+password visible for a short time to everyone on your system:
+
+.. code-block:: sh
+
+   curl -X POST -c cookie.txt -D head.txt -d username=<USERNAME> -d password="$PW" --insecure "https://<SERVER>/login
+
+Now ``cookie.txt`` contains the required authentication token information in the ``SessionToken``
+cookie (url-encoded json).
+
+.. rubric:: Example token content
+
+.. code-block:: json
+
+   ["S","PAM","admin",[],[],1682509668825,3600000,"Z6J4B[...]-OQ","31d3a[...]ab2c10"]
+
+Using the token
+~~~~~~~~~~~~~~~
+
+To use the cookie, pass it on with later requests:
+
+.. code-block:: sh
+
+   curl -X GET -b cookie.txt --insecure "https://<SERVER>/Entity/123"
+
+.. _curl-logout:
+
+Logout
+~~~~~~
+
+Use the cookie on the ``logout`` resource to invalidate the session:
+
+.. code-block:: sh
+
+   curl -X GET -b cookie.txt --insecure "https://<SERVER>/logout"  # Now the cookie is invalidated.
+   curl -X GET -b cookie.txt --insecure "https://<SERVER>/Entity/123"  # Should fail with 401 - Unauthorized.
+
+
+Outdated information?
+=====================
+
+The text below may be outdated.
 
 Request Challenge
-^^^^^^^^^^^^^^^^^
+-----------------
 
-* ``GET http://host:port/mpidsserver/login?username=$username``
-* ``GET http://host:port/mpidsserver/login`` with ``username`` header
+* ``GET http://host:port/login?username=$username``
+* ``GET http://host:port/login`` with ``username`` header
 
 **No password is required to be sent over http.**
 
@@ -61,7 +127,7 @@ Pseudo code:
    $solution = sha512($hash + sha512($password))
 
 Send Solution
-^^^^^^^^^^^^^
+-------------
 
 The old ``$hash`` string in the cookie has to be replaces by ``$solution`` and
  the cookie is to be send with the next request:
@@ -80,32 +146,3 @@ The server will return the user's entity in the HTTP body, e.g.
 
 and a new AuthToken with ``$mode=SESSION`` and a new expiration date and so
 on. This AuthToken cookie is to be send with every request.
-
-Logout
-^^^^^^
-
-Send
-
-``PUT http://host:port/mpidsserver/logout``
-
-with a valid AuthToken cookie. No new AuthToken will be returned and no
-AuthToken with that ``$session`` will be accepted anymore.
-
-Commandline solution with ``curl``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To use curl for talking with the server, first save your password into a
-variable: ``PW=$(cat)``
-
-The create a cookie in ``cookie.txt`` like this (note that this makes your
-password visible for a short time to everyone on your system:
-
-.. code-block:: sh
-
-   curl -X POST -c cookie.txt -D head.txt -H "Content-Type: application/x-www-form-urlencoded" -d username=<USERNAME> -d password="$PW" --insecure "https://<SERVER>/login
-
-To use the cookie, pass it on with later requests:
-
-.. code-block:: sh
-
-   curl -X GET -b cookie.txt --insecure "https://<SERVER>/Entity/12345"